Timeline for Coding standard for clarity: comment every line of code?
Current License: CC BY-SA 3.0
17 events
| when toggle format | what | by | license | comment | |
|---|---|---|---|---|---|
| Nov 25, 2016 at 11:16 | comment | added | Ewan | i should have commented my comment!! | |
| Nov 25, 2016 at 11:09 | comment | added | SantiBailors | @LightnessRacesinOrbit If Ewan's point was the misspelling of stream then I also think the compiler would catch it, but my initial interpretation was different: due to your example being about closing a stream and his reply being about opening one, I thought that his point was that the comment says "close the stream" and the code does the opposite. If it's the latter, I think that even such a comment would not be useless at all because it would allow to easily spot the error. Of course it might be the comment which is wrong, but now we got the chance to spot the potential error and check. | |
| Nov 22, 2016 at 0:17 | comment | added | Ewan | its ok to run your code through autocorrect as a precompile step right?? | |
| Nov 21, 2016 at 20:07 | comment | added | Lightness Races in Orbit | @Ewan: Your compiler will catch the misspelling of stream and the missing argument to open() :) | |
| Nov 21, 2016 at 13:06 | comment | added | Ewan | its not useless if its followed by steam.open() | |
| Nov 21, 2016 at 13:02 | history | edited | Ewan | CC BY-SA 3.0 | added 476 characters in body |
| Nov 21, 2016 at 12:59 | comment | added | Lightness Races in Orbit | An example of a useless comment is // close the file stream | |
| Nov 21, 2016 at 12:58 | comment | added | Lightness Races in Orbit | An example of a useful comment is // seek()ing here rather than ignore()ing due to libstdc++ bug #{NNNNNN} (which will {blah the blah} rather than {fonzle the fonz}): https://stackoverflow.com/q/40308080/560648 | |
| Nov 21, 2016 at 12:55 | comment | added | Lightness Races in Orbit | @AndrewTFinnell: "In 20 years I've never seen someome comment prototype their code this way then fill in the gaps with actual code" I do it when the requirements are more than trivial - it helps with the thought process. However, the comments won't last more than twenty minutes and I certainly would not leave them in afterwards. They may (probably will) be replaced by meaningful explanatory comments for any non-trivial code lines. | |
| Nov 21, 2016 at 1:56 | comment | added | jscs | Yes, indeed, the Pseudocode Programming Process -- I'd forgotten the name. I don't have my copy of the book available, but I'm quite certain the pseudocode/comments are not removed strictly. One of the advantages of the process is that useful comments are a consequence of it. | |
| Nov 20, 2016 at 22:11 | comment | added | David Arno | @JoshCaswell & Ewan, yes it was a technique many years ago and did indeed predate TDD. But, you were meant to delete the comments afterwards! And TDD has completely supplanted it as a sensible way of creating code that meets a spec. | |
| Nov 20, 2016 at 20:57 | comment | added | Ewan | I think you misread the question. every line commented is an extreme example to avoid | |
| Nov 20, 2016 at 20:53 | comment | added | Andrew T Finnell | Are you talking about the Pseudocode Programming Process? The purpose of that was to reduce comments. I don't ever remember that book stating the comments should be left in the code. And commenting to produce a conceptual procedure is meant to be high level, not low level. If one were to comment every line they intended to write they could have just written the lines. The idea is to prototype out the principals of the code not each line. The book does not suggest commenting every line. That is the focus of this question. And I could be wrong, but I believe that's in the Second Edition. | |
| Nov 20, 2016 at 20:28 | comment | added | Ewan | also predates tdd i believe | |
| Nov 20, 2016 at 20:16 | comment | added | jscs | While I don't think the code in the question is a good example of this, the practice of writing out a procedure in comments first, and then going back and filling in the code is specifically called out in "Code Complete" as a one possible practice to help produce readable code, @AndrewTFinnell. It's definitely not unheard of, even if it's outside your experience. | |
| Nov 20, 2016 at 20:04 | comment | added | Andrew T Finnell | In 20 years I've never seen someome comment prototype their code this way then fill in the gaps with actual code. There is already an objective way to achieve what you're saying, or what I think you're saying. It's called Test Driven Development. The Unit Tests define the spec and whether the code adheres to that spec. All without comments. | |
| Nov 20, 2016 at 17:45 | history | answered | Ewan | CC BY-SA 3.0 |