3 ms·
This is one of the reasons I tend to prefer comments over external documentation whenever possible. No, there's no magic force keeping comments in sync with the
by jerf 7y ago
This is one of the reasons I tend to prefer comments over external documentation whenever possible. No, there's no magic force keeping comments in sync with the code they document changes, but you at least have a fighting chance. Programmers have enough state to juggle in their head as it is without expecting them to even necessarily know what all the external documentation it is they should update. Heck, even with comments it can be bad enough knowing whether some change to this module necessitates changes to comments in other modules in the code that you may have just looked at.
It isn't always possible. Very high-level architecture may belong in a format where diagrams are more available, and the high-level design justification for the project itself doesn't have a great place in the code.
- a1369209993 7y agoSimilarly, I try to bake the documentation directly into the code. Eg (from a shell): OPTION(*line=='[',"[EXPR]","the result of evaluating EXPR as a math expression (see -?m)") { ... } qsh -?s | grep -F '$[' '$[EXPR]': the result of evaluating EXPR as a math expression (see -?m) So OPTION does triple duty as 'comments', documentation, and the actual test for what kind of substitution is being parsed. This tends to be at the mercy of code structure though.
- xchaotic 7y agoWithout context, I have no idea what are you trying to imply or document with OPTION? I can more or less figure out what the code does, but not why it does it. Here you should document why are you grepping for something