Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Writing Well-Documented Code – Learn from Examples

codecatalog.org

Post reply on HN
Print view View original

81–90 of 153 posts

Re: Writing Well-Documented Code – Learn from Examples

#81

Post by audit »

codethief wrote: post #6

Speaking of source code comments, antirez (of Redis fame) wrote a fantastic article[0] about that topic some time ago and I still recommend it to colleagues whenever they make the hollow statement that "code should and can be intelligible on its own, without any comments". [0]: https://web.archive.org/web/20210226004600/http://antirez.co... (I still don't understand why he deleted his blog)

Thank you for this link. I appreciated antirez's categorization: " During my research I identified nine types of comments:

- * Function comments - * Design comments - * Why comments - * Teacher comments - * Checklist comments - * Guide comments - * Trivial comments - * Debt comments - * Backup comments

"

I tend to write 'debate comments' of the software that I write for my own business (sole proprietor). I think they fit the 'why' category above.

I often doubt my own decision making process, so I tend to write it out in comments, so that I can I can see reasoning.

My general challenge with comments is of 'maintanence'. The tools to maintain comments, cross link them across diagrams or other hand-written documents -- are hard to find.

So am gradually switching to my own directive that 'all documents about implementation, the API and their usage, are to be generated from my comments'.

Again, not a lot of tools that I found in this area, but at least it is possible to write my own tools (using IDE APIs) in this area.

Re: Writing Well-Documented Code – Learn from Examples

#82

Post by einpoklum »

cratermoon wrote: post #50
abootstrapper wrote: post #35

Earlier quoted context omitted.

I agree with you. Code should be intelligible on its own without comments. It should also be well documented. One does not preclude the other.

I've forgotten who first wrote this, so I can't credit them, but there's a saying that if someone can't write clear, clean, and understandable code , why does anyone expect them to be able to write clear, clean, and understandable English (or whatever language)? It's quite a bit easier to write something the compiler or runtime can understand, there's no need for meaningful names, consistent structure, or conceptual…

> if someone can't write clear, clean, and understandable code, why does anyone expect them to be able to write clear, clean, and understandable English (or whatever language)?

The comments don't say the same thing as the code. In the comments, the author might tell us - albeit not clearly or in proper English, what they want to achieve, or why they're doing it this way.

Re: Writing Well-Documented Code – Learn from Examples

#83

Post by ridiculous_fish »

didip wrote: post #11

I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.

How do you know what a function does, without a "what" comment to explain it? Even "obvious" functions like Math.max have edge cases, and I rely on "what" comments to understand how those cases are handled.

Re: Writing Well-Documented Code – Learn from Examples

#84

Post by jmartrican »

I have seen two extremes on this over the years... comment a lot, or do not comment at all. In the teams I work in, I would love to see a more moderate and practical view on the matter.

I get the whole document with your code, and practice that. But sometimes we end up with variable names that get very long and start leading not the most aesthetic code that gets formatted in a very vertical way.

Don't know the right answer, but suspect the two extreme views are not correct.

Re: Writing Well-Documented Code – Learn from Examples

#85

Post by einpoklum »

didip wrote: post #11

I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.

I upvoted you, but there are plenty of exceptions. For example:

* Common name of the algorithm you're using

* Reference to somewhere else in the code that's related

* "You may think this code only does X, but it really also does Y"

* "We used to also do XYZ here, but that was removed because of ABC"

and so on.

Re: Writing Well-Documented Code – Learn from Examples

#86

Post by t-3 »

pcmoney wrote: post #36

Personally I found most of those examples to be not great. I think they would be improved better names overall, more well named private methods and most importantly well structured companion test classes proving the behavior. I really dont want to read another developers comments on their mental state while I am feverishly debugging their code during a 3am page. The number of times I have been misled by an outdated c…

Exactly. In my opinion, Thinking Forth by Leo Brodie should be required reading for anyone who touches code.

Re: Writing Well-Documented Code – Learn from Examples

#87

Post by dmurray »

Zababa wrote: post #58
jpswade wrote: post #33

The code should explain what it's doing (self documenting code) and tests should explain why it's doing it. Comments tend to just become a place for misinformation or get disconnected from the actual logic. Adding more comments sometimes doesn't clarify the situation, it just acts as a second source of truth.

> and tests should explain why it's doing it I was going to say "So for performance "hacks" there should be a clean implementation that's benchmark against the current implementation for example?" as a way to disprove what you said, but while writing it I realized that it may actually be a pretty good idea.

Yes, there should pretty much always be this.

You've just written some messy unclear code for performance reasons, so it deserves more thorough tests than average.

And you've already written the clean version anyway, since you hopefully didn't write the optimized version until after you profiled the slow one. So it's not even significant extra work to turn that into your test suite.

Re: Writing Well-Documented Code – Learn from Examples

#88

Post by Zababa »

dmurray wrote: post #87
Zababa wrote: post #58

Earlier quoted context omitted.

> and tests should explain why it's doing it I was going to say "So for performance "hacks" there should be a clean implementation that's benchmark against the current implementation for example?" as a way to disprove what you said, but while writing it I realized that it may actually be a pretty good idea.

Yes, there should pretty much always be this. You've just written some messy unclear code for performance reasons, so it deserves more thorough tests than average. And you've already written the clean version anyway, since you hopefully didn't write the optimized version until after you profiled the slow one. So it's not even significant extra work to turn that into your test suite.

This could also be a great way to check if your optimized version is still necessary with new versions of your language implementation. The more I think about it, the more it seems like a great idea.

Re: Writing Well-Documented Code – Learn from Examples

#90

Post by samsquire »

seanwilson wrote: post #69

For the first example with conditions, I much prefer rolling the "why" of the comments into boolean variable names where possible e.g. // We still have burst budget for *all* tokens requests. if self.one_time_burst >= tokens { ... } else { // We still have burst budget for *some* of the tokens requests. becomes something like (I'm missing context but you get the idea): enoughBudgetForAllTokenRequests = self.one_time_…

Long variable names mean you perceive your simple code as being too complicated. It's an if statement. I would refactor your long variable name to something more compact like enough_budget.
Post reply on HN