The Protobuf documentation made me cringe. Every character of its "personality" adds a cognitive burden for the reader and a maintenance burden for anyone who has to update it. If a developer wants to be cute with the same brevity and clarity that the comments would have otherwise, fine. Otherwise it's self-indulgent performative trash that should be rejected in review.
Writing Well-Documented Code – Learn from Examples
51–60 of 153 posts
Re: Writing Well-Documented Code – Learn from Examples
#52Time and active readers.
Want well documented (and tested and thought out) code?
Then give the coders people outside of their team / hierarchy who are going to check it / read it / use it.
And then give them time.
And repeat.
Re: Writing Well-Documented Code – Learn from Examples
#53Well documented code is respectful of the maintainer's time. Nobody wants to read a monologue full of noise to understand what is happening. Comments are not monologues. Explain what the line you are commenting does, and perhaps elaborate why. But always acknoweledge: more words = more patience required = more maintenance cost. Also, nobody will care about what your name is in 2 years. Do not make the code about you.
On the other hand, if something is missing in the comments, it could take days to find out exactly what you need. Maybe a "level of comments" like log levels could help here?
Making it easy to hide comments == making it easy to forget to update comments.
Re: Writing Well-Documented Code – Learn from Examples
#54Earlier quoted context omitted.
Wow, you just opened my eyes – I really thought he had deleted his blog! Must be the HTTPS Everywhere extension I'm using – though I really don't understand why it redirects me to redis.io just because antirez's TLS certificate is for redis.io, not antirez.com. I would really prefer a clear error message here.
The web server(s) at antirez.com are weirdly configured. So it’s not so easy for the web browser to display a very clear error message in this case. If you run this command you can see a little more clearly what’s going on: wget --no-check-certificate -S -O - https://antirez.com/news/124 If you use the plain HTTP URL, everything works fine. If you try https://antirez.com/news/124 the web server at antirez.com:443 wil…
Looks like the cert is for a different domain (redis.io) AND it expired August 7, 2020.
Re: Writing Well-Documented Code – Learn from Examples
#55Worth comparing: http://steve-yegge.blogspot.com/2008/02/portrait-of-n00b.htm... A "n00b" is scared of code, and wants as much help to understand it as possible. An "expert" already knows all they need to know to work on the code, and is more productive by putting as much code on the screen as they can.
Rather.. I think part of the point is, context matters. If the team is small, and the project is changing rapidly.. I think the needs and expectations for documentation are different than if the project or team is large and change is slow.
Re: Writing Well-Documented Code – Learn from Examples
#56Earlier quoted context omitted.
On the other hand, if something is missing in the comments, it could take days to find out exactly what you need. Maybe a "level of comments" like log levels could help here?
Making it easy to hide comments == making it easy to forget to update comments.
That's a good point. Maybe add a check if the function changed and the comment didn't to remind people? But comment are already easy to forget to update, as they are not code.
Re: Writing Well-Documented Code – Learn from Examples
#57Speaking 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)
I love this line: "Comments are rubber duck debugging on steroids, except you are not talking with a rubber duck, but with the future reader of the code, which is more intimidating than a rubber duck, and can use Twitter."
Re: Writing Well-Documented Code – Learn from Examples
#58The 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.
Re: Writing Well-Documented Code – Learn from Examples
#59I have a simple rule to go by. Comments should describe “why” and the code should describe “what”.
WHY comments drastically improved my code.
I’ve similarly been paying much more attention to convey INTENT which I think is massively missing from computer science. The code might suck, but if the intent is clearly defined, it helps to refactor later.
Re: Writing Well-Documented Code – Learn from Examples
#60Speaking 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)
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'm not sure we agree. But I guess the question comes down to what you and I mean by "intelligible".
antirez provides several examples where the code without the comments would be much harder to understand and/or maintain. Whenever this is the case, I would argue that comments are a must and without them the code is at least barely intelligible.