Portrait of a Noob
steve-yegge.blogspot.com
Portrait of a Noob
1–10 of 43 posts
Re: Portrait of a Noob
#2I read this a while back and i still remember the takeaway point from it :
"It's denser: there's less whitespace and far less commenting. Most of the commenting is in the form of doc-comments for automated API-doc extraction"
This is right on the button. I prefer writing/reading an overall README.txt which says concisely what that module/package etc. is supposed to do and doc-comments where appropriate when something is not obvious. Anything else and i automatically start seeing that as noise filtering it as i go along. The worst are the obvious and/or the outdated ones.
Re: Portrait of a Noob
#3This is one of Yegge's most stupid rants. I strongly recommend SQLite Dr. Hipp's video presentations on how to write well commented code.
Re: Portrait of a Noob
#4If it was poorly written code, I'd rather see those huge comments just so I knew what was going through the authors head. I think if it's poorly written code with "no" comments, then you have even bigger problems.
I want to say I read that entire article, but I only read the first few paragraphs, so, my comment may be off topic somehow. That was a hefty post!
Re: Portrait of a Noob
#5That's a very large function for an experienced programmer. In my opinion, each function should do one thing and that thing should be the name of the function.
Re: Portrait of a Noob
#6Old HN thread about this essay: http://news.ycombinator.com/item?id=113244
Re: Portrait of a Noob
#7That's a very large function for an experienced programmer. In my opinion, each function should do one thing and that thing should be the name of the function.
Only because of comments, an indentation style that pairs function argument on lines, etc. It's not a big function in the sense you're thinking, and breaking it up further may be counterproductive.
Re: Portrait of a Noob
#8I read this a while back and i still remember the takeaway point from it : "It's denser: there's less whitespace and far less commenting. Most of the commenting is in the form of doc-comments for automated API-doc extraction" This is right on the button. I prefer writing/reading an overall README.txt which says concisely what that module/package etc. is supposed to do and doc-comments where appropriate when something…
There's a big difference between "what"/"how" and "why" comments. "This increments a variable" is a stupid comment because the code already says it, but a note such as "I'm using this particular data structure/algorithm/etc. because ..., even though ... seems like a better choice" can speak volumes. It's hard to make code itself clearly convey intent (careful naming is the main way), and it's the first thing to get buried by verbose code.
If you have documentation about the design of the system and write reasonably clear code, you can document sparsely. (Having fewer comments also gives those present added emphasis.) As with most engineering, it's more about trade-offs than hard-and-fast rules, though.
Re: Portrait of a Noob
#9I'm not a big fan of lots of comments in the code itself, but I very much so advocate design documentation.
I once had the pleasure of rewriting an Ada avionics subsystem in C. The code was very tersely commented, and the only documentation I could find on the subsystem was a requirement to the effect of "such-and-such subsystem shall exist". So I was left to figuring out what the subsystem worked from the code itself.
That's possible to do, but things would have gone a lot faster if I would have had a few pages describing what the goals and overall architecture of the software was.
Re: Portrait of a Noob
#10Comments are invisible until the moment you need them.
When you understand your code, you don't bother to read the comments. As soon as you forget how the code works, you look to the comments for direction.
But if you didn't revise your comments along with your code, the comments will trick and deceive you until you realize that they're out of date. So you must re-grok the code anyway.
Use comments to describe your code's purpose. Let your code self-document the implementation.If you are particularly clever in your implementation, add a quick comment to explain your cleverness. When you realize you shouldn't have been so clever, be sure to remove the implementation comment as well.