3 ms·
> 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 practi
by TeMPOraL 6y ago
> 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.
- pdimitar 6y agoOne could argue that the realization that this should be done in the first place is the skill your parent commenter was talking about.
- watwut 6y agoThese 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.
- TeMPOraL 6y agoIt 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.
- variaga 6y agoWhat'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". E.g. char* strncpy(char *dst, const char *src, size_t n) and size_t strlcpy(char *dst, const char *src, size_t size) 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.
- TeMPOraL 6y agoI mostly agree with what you wrote, but then take a look at the man pages for the two functions you mentioned: https://linux.die.net/man/3/strlcpy https://linux.die.net/man/3/strlcpy https://linux.die.net/man/3/strncpy https://linux.die.net/man/3/strncpy 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.
- dragonwriter 6y ago> 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.