Timeline for Coding standard for clarity: comment every line of code?
Current License: CC BY-SA 3.0
7 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Nov 24, 2016 at 15:27 | comment | added | Tony Ennis | I'm not making this up - in order to meet a Canadian requirement, a company I worked at had the developers write a pre-processor that added comments EXACTLY like the OP's example. I think ours was "C ADD 1 TO I" or some such. It was FORTRAN, so loops were similarly commended "C LOOP FROM 1 TO 10". The code was LOADED with useless comments. I deleted all that crap as I maintained code. No one ever said anything to me. | |
| Nov 23, 2016 at 16:06 | comment | added | Andrew T Finnell | The use of a comment standard such as JSDoc, JavaDoc and Doxygen are meant for providing searchable and human readable documentation, as @Graham said. The line of code mentioned in this answer has nothing to do with Doxygen. I cannot even imagine a rule set being in place which would parse that comment and produce an entry in the outputted documentation. When you look at the Docs for JMI, the Java Standard Libraries, etc. they are all produced using a tool very similar to Doxygen. That's the purpose of it. Not what's said here | |
| Nov 23, 2016 at 13:32 | comment | added | Graham | Aren't you contradicting yourself? I think we'd both agree that it's critical for a function to have a comment describing what it does from a black-box perspective - "these inputs go in, the function does this, and these outputs come out". It forms the contract between the person who wrote the function and the people who use the function. The purpose of Doxygen is simply to standardise the format of those comments in a way which can be parsed and made searchable/indexable. So why would you want a "good comment block" but not want it in a standard, human- and machine-readable format? | |
| S Nov 22, 2016 at 12:42 | history | suggested | alexyorke | CC BY-SA 3.0 |
Put code in code blocks
|
| Nov 22, 2016 at 0:16 | review | Suggested edits | |||
| S Nov 22, 2016 at 12:42 | |||||
| Nov 20, 2016 at 22:36 | comment | added | cmaster - reinstate monica | +1 for the doxygen comment: This is precisely my objection to including doxygen "documentation" in my code; 95% of the time it just repeats what's already obvious from the function signature. I, too, have not seen a single doxygen documentation that's worth anything, yet. Writing those comments wastes time three times: Once to write the comments, once to read them again, and once to debug problems created by stale comment content. | |
| Nov 20, 2016 at 21:45 | history | answered | jamesqf | CC BY-SA 3.0 |