Timeline for How do I document my code for minimum time review?
Current License: CC BY-SA 3.0
22 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Mar 12, 2018 at 21:04 | comment | added | Frank Hileman | I suspect your metric for "readable" is not the same as those reading your code. Comments can be good or bad, just like code. They can be redundant or critical for understanding. Engineering code is often an implementation of an algorithm in a book or paper, with complex formulas. Assuming the reader can understand the (extremely complex) code, without references back to the original source is a typical mistake engineers make in their code. I always ask them to add comments in this case. | |
| Mar 10, 2018 at 15:09 | comment | added | angrydust | @Eric Good point, although I then raise to you cmaster's example of a comment about why something was not done. | |
| Mar 9, 2018 at 22:19 | comment | added | Frank Hileman | @DavidArno Documentation comments are comments that can be extracted from the code, and processed using a tool, that then reformats the contents into a more readable form, usually a type of web format. Having worked on reference documentation the old way, and used documentation comments for 14 years or so, I can say that the automated process has saved me tremendous amounts of time. | |
| Mar 9, 2018 at 11:57 | comment | added | Ralf Kleberhoff | I like the "1000ft view document" idea. That's the one document I miss most when trying to understand someone else's code. | |
| Mar 9, 2018 at 10:05 | comment | added | Eric |
@theguywholikeslinux I disagree with the example, because you could write throw exception "We assumed xyz, so this shouldn't have happened.".
|
|
| Mar 9, 2018 at 9:43 | comment | added | anon | @DavidArno: As it should be! | |
| Mar 9, 2018 at 9:19 | comment | added | David Arno | @JackAidley, That's fine. My bit about the comments is probably the most important point in my answer as it's the part most folk get wrong. I appreciate others will disagree, but expressing what I've found to be the best approach to writing readable code is way more important to me than avoiding downvotes. | |
| Mar 9, 2018 at 9:15 | comment | added | anon | I agree with most of this answer, but the part about comments is so bad, I have to downvote it. | |
| Mar 8, 2018 at 20:54 | comment | added | Ti Strga | As a historical comment on the "clever" code: in a plea for clear and straightforward code, Kernighan & Pike argued that (paraphrasing) to debug something, you have to be twice as smart as the person who wrote it. If you write code that's as "clever" as you can be, you are by definition not smart enough to debug it. | |
| Mar 8, 2018 at 19:34 | comment | added | David Arno | @FrankHileman, nope it really isn't universal. In fact I have a reasonably popular library that contains zero comments. The documentation is hand-written, thus both adds to the information already in the code and avoids cluttering the code with that documentation. Documentation comments are a really crappy way of producing API docs. They're a classic "emperor's new clothes" scenario. | |
| Mar 8, 2018 at 19:15 | comment | added | Frank Hileman | Documentation comments are universally used in public APIs; without them, the API is unlikely to be used. It is a code smell to avoid them, not to add them. For me, "self documented code" is the same as "only the original author can understand or love this code". I don't know why it is, but the less documentation, the more likely the author believes it is easy to understand. | |
| Mar 8, 2018 at 18:51 | comment | added | David Arno | @R.Schmitz, Spot on: code smells are an indication that something might be wrong. In most cases it is. There are edge cases though. Comments explaining work-arounds to third party bugs are one such edge case. | |
| Mar 8, 2018 at 18:18 | comment | added | R. Schmitz | I like it even more dramatic: every comment is a failure to express yourself well in code. For example, I have a 4 line comment in one method, explaining the workaround for a 3rd party bug. I failed to express that well in code, so it's in a comment. I'd say it improved readability tough, because I doubt anybody would enjoy scrolling horizontally to read a very long and very descriptive method name. "Comments are a code smell" - yes, but we have to remember that not everything that smells is sh*t. | |
| Mar 8, 2018 at 16:49 | comment | added | cmaster - reinstate monica |
I think, the most important point about comments is, that they should be written at the highest possible abstraction level. No-one profits from comments like i++; //next index or //> parameter 'foo': a Foo instance, but comments explaining why a class exists, what use cases it was designed to facilitate, what other classes it exists to serve, etc. are valuable. This actually goes quite well with your 1000ft view document, but is at an intermediate level. The more you get down to the implementation, the less comments you should find.
|
|
| Mar 8, 2018 at 16:37 | comment | added | cmaster - reinstate monica |
@DavidArno But you cannot do that for a comment explaining why something was not done. Like //XXX: Not using straight-forward method Foo here because .... Such comments can be immensely valuable, but are impossible to convey with code for obvious reasons.
|
|
| Mar 8, 2018 at 16:34 | comment | added | magu_ | Very nice list. But like @Jonathan. I do not agree with the comments. Some times you have to account for bugs in a third party frameworks though. While this can be refactored into its own function it's still nice to leave a bit of description to why the workaround (bugnumber or bugname/description of the bug) is required. | |
| Mar 8, 2018 at 14:48 | comment | added | angrydust |
We've all seen our fair share of // increment x x++; comments that are of no use, but it's wrong to throw the baby out with the bathwater and declare that comments are always bad. For example, comments of the form // this case should never happen because xyz throw exception "unreachable".
|
|
| Mar 8, 2018 at 14:01 | comment | added | David Arno | @Jonathan. From experience, all such comments can be replaced with extracting out that piece of code into another function and using the function name to explain why. So my "no comments" position stands in my view. | |
| Mar 8, 2018 at 12:58 | comment | added | Jonathan |
I agree with all your point, except that comments do have their place. While I agree there's no point in comments like add 1 to i, comments should explain why the code does what it does. For example, the code if (!something.Exists()) {...} can use a comment like: // something exists only when (explanation of the broader scenario).
|
|
| Mar 8, 2018 at 10:40 | history | edited | David Arno | CC BY-SA 3.0 |
added 36 characters in body
|
| Mar 8, 2018 at 10:08 | history | edited | David Arno | CC BY-SA 3.0 |
added 217 characters in body
|
| Mar 8, 2018 at 10:01 | history | answered | David Arno | CC BY-SA 3.0 |