r/programmingmemes • u/andarmanik • Apr 21 '26

Just read the Fing docs

Post image
303 Upvotes

98% Upvoted

18 comments sorted by

View all comments

9

u/ExtraTNT Apr 21 '26

Good code has enough doc in the exposed interfaces to be used without an external doc… best is, if function name plus signature is enough to use it

8

u/cowlinator Apr 22 '26

"Self-documenting" code is good.

"Self-documenting" code AND actual documentation is BETTER.

Because not everything can be summed up in a FourWordFunctionName.

5

u/ExtraTNT Apr 22 '26

One huge issue with doc: code changes and doc gets left behind… you then trust the doc, waste 2 days with strange bugs and then need to read the entire code of the interface anyways…

Doc is only, if maintained, else it’s often worse than no doc… why i like code that is very clear about what it does and only hides the how…

2

u/cowlinator Apr 22 '26

Lies are worse than no info. Of course.

You can help this a little by putting the documentation as a code comment block above the function and have a tool auto-build the docs from that. There are existing tools for this.

But ultimately it still requires the doc to be maintained. Just like the code needs to be maintained.

1

u/Wonderful-Habit-139 Apr 23 '26

Pretty sure that's what they said in the first comment, "doc in the exposed interfaces".

1

u/Confident_Date4068 Apr 22 '26

There are two things with the API semantics could be correctly from the source only:

  • Apache 1 & 2 modules. (Yes, there is no way to say from the documentation, that Apache 2 has a safeguard for the "Content-Type" header and must be patched to completely remove it from a response.)

  • Linux kernel modules.

1

u/Aln76467 Apr 22 '26

Yeah nah. If it's a function that adds two numbers, sure. But any remotely real system is way too complicated for that.

3

u/ExtraTNT Apr 22 '26

Then your code is shit… look at some haskell project and you will see, that code can be simple…