Documentation is a skill. Like any skill it takes practice.
I have moved to a FAANG and their documentation is downright fucking awful. _everyone_ just writes code, with lots of "clever" bits, and doesn't bother to fucking comment.
Not only that because people don't even _comment_ their code, the wiki is a total shit show. Want to know how to use a Queue? tribal knowledge. want to know which DB is best for x? tribal knowledge. Want to know how to create a new endpoint? tribal knowledge.
Worse still, we had a class during induction where some ponytailed "10x" said "If you are messaging me asking questions, I can't help other people" I didn't have the bollocks at the time to ask why his documentation sucked arse. There seemed to be a weird pride in the fact that people needed to message him to figure his shit code.
The moral of the story is this:
fuck off with your clever code, spend that effortyou put into learning new languages, or trying a new techniques and put it into developing your writing skills. It takes empathy, organisation and skill. It'll make you a better programmer and a better person.
> Documentation is a skill. Like any skill it takes practice.
The type of documentation you described - code comments and wiki entries - they don't need practice. They only need care.
If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it:
//! Transform Foo into Bar
//!
//! Foo must be an X-ing Quux adhering to Y.
//! Foo is not modified.
//! Returns a Bar that is Z.
No knowledge or skill needed. And will make everyone's day nicer.
I'm not sure what to do about lack of care in a team/company, other than trying to promote it by example.
These seem too me mostly useless comments. I need comments for things that are not apparently visible. Transforms foo into bar is either clear from params and return types, or should be from name. Likewise, in most cases it is easy to see whether argument changes.
The parts that are difficult to see and difficult to understand are the one that need documentation. They are the ones that happen to be difficult to explain.
What's missing IMO from those example comments (and most automatic documentation) is the "why". I can almost always look at the code to figure out that a function takes a Foo and returns a Bar. What's almost never obvious from the code itself is "why would I want to convert a Foo to a Bar" or "under what circumstances should I use this function instead of something else".
both copy a string from src to dst with a limit on the number of bytes copied. Good comments for would not simply explain what they do and what the arguments/returns represent, but under what circumstances to prefer each variant.
Going with the "6 W's":
"How" (does this code work) and "What" (does this code do) can mostly be explained by the code itself, although comments should be used to clarify anything non-obvious, for instance if you're depending on a side effect or something.
"Where" (should you use this code) and "why" (should you use this code) need to be covered by comments. It is extremely hard to figure those out from the code alone.
"Who" (wrote it) and "when" (was it written) should be in the version control system metadata. Putting those in comments is a good way to ensure the comments are out-of-date/wrong in any long-lived codebase.
Note how most of the text there is focused on the "How" and "What", because both functions have a bunch of requirements for their arguments that are not expressed in their respective signatures.
Some languages have better tools for expressing these requirements in code. But when they can't be expressed in a way that can be enforced by the compiler, IMO they absolutely need to be mentioned in an interface-level comment (i.e. above function signature), to give users a fighting chance of avoiding bugs.
Also worth noting that the particular constraints around strncpy() and strlcpy() will not be obvious in the implementation either - the programmer trying to make use of these functions would have to study the implementation to notice potential issues. A well-placed comment can save them an expensive context switch here.
It depends on the language. Perhaps Haskell will not need such comment at all.
In C++, at the very least the preconditions X and Y, as well as the invariant Z, will usually not be apparent from the function signature. Whether the argument is modified? That's usually clear from the use of const... except when it isn't, e.g. because the function is a universal-reference template, or some C compat thing that must use bare pointers because reasons.
In JavaScript, you won't even know Foo, Bar and Quux, unless someone puts it in the function name.
The primary benefit of such comments is to encode enough information that isn't obvious from the signature, that you don't need to read the actual implementation. It's particularly useful if you're using an editor or IDE that can pull signature comments and show them during auto-completion - it saves you from constantly jumping into other places in the codebase, just to verify if you're picking the correct function for the task.
> The type of documentation you described - code comments and wiki entries - they don't need practice.
Yes, they do.
> They only need care.
They need that, too, but “care” is what gets you to apply what you know of how to do it rather than neglecting it, but practice (and interactive practice with feedback, specifically) is how you develop the skill to make useful comments, and ideally only useful comments.
> If you know how to write a function that takes Foo and transforms it into Bar under conditions X and Y, you also know how to just append this above it:
Well, mechanically probably you know how to. But absent relevant practice you might not know that (assuming, for the sake of argument, that this is correct in context — and in many cases, IMV, it wouldn’t be as much of that seems to reiterate information that is contained in type signatures and thus violate the principle of single source of truth if placed in comments) you should prepend comments with that content, rather than none or some other content foe the function.
I just make sure I supply a detailed what, why and how comment with each commit and then copy and then just export that for documentation. Also spending time putting thought into a standard system for properly naming variables in your app goes a long way. A lot of people like to abbreviate things just to avoid typing. Modern IDEs allow autocomplete so there is little excuse for this. The only time that is acceptable is in a very small very self evident class, method or function that does something very simple and atomic. I try to avoid this as well since I like to be able to do named search and replaces later if needed. Too simple of a variable name will lead to collisions with sed/awk ect
I have moved to a FAANG and their documentation is downright fucking awful. _everyone_ just writes code, with lots of "clever" bits, and doesn't bother to fucking comment.
Not only that because people don't even _comment_ their code, the wiki is a total shit show. Want to know how to use a Queue? tribal knowledge. want to know which DB is best for x? tribal knowledge. Want to know how to create a new endpoint? tribal knowledge.
Worse still, we had a class during induction where some ponytailed "10x" said "If you are messaging me asking questions, I can't help other people" I didn't have the bollocks at the time to ask why his documentation sucked arse. There seemed to be a weird pride in the fact that people needed to message him to figure his shit code.
The moral of the story is this:
fuck off with your clever code, spend that effortyou put into learning new languages, or trying a new techniques and put it into developing your writing skills. It takes empathy, organisation and skill. It'll make you a better programmer and a better person.