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

Portrait of a Noob

steve-yegge.blogspot.com

Post reply on HN
Print view View original

11–20 of 43 posts

Re: Portrait of a Noob

#11

Post by steveklabnik »

mcav wrote: post #10

Comments 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 c…

This is why api-level documentation is great: functions are used for a purpose, and they're supposed to be a black box. If you keep your functions small and focused, you can just describe what they do, and it all works out.

Re: Portrait of a Noob

#12

Post by aidenn0 »

tjr wrote: post #9

I'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 itsel…

Things only go faster if the design documentation matches the code. This is, in my experience, never.

In the best case, the design documentation is updated as the code is written and problems are found. However, even then, decisions made while coding will avoid problems, and ambiguities in the design documentation don't get updated when that happens.

I've had to do similar rewrites in the past, and I usually just skim the design documentation to get some idea of what the plan was. However, programming languages are in general the most concise and unambiguous way to represent what a program does.

Re: Portrait of a Noob

#14

Post by NathanKP »

From the article:

If you're a n00b, you'll look at experienced code and say it's impenetrable, undisciplined crap written by someone who never learned the essentials of modern software engineering. If you're a veteran, you'll look at n00b code and say it's over-commented, ornamental fluff that an intern could have written in a single night of heavy drinking.

I have never seen this so succinctly expressed before.

Re: Portrait of a Noob

#15

Post by ivenkys »

silentbicycle wrote: post #8
ivenkys wrote: post #2

I 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…

Yup , that was my point on the "doc-comments where appropriate". Overall design of the system can/should be expressed with a good,well-written README.txt. I know UML is "supposed" to solve that problem but not for me.

Re: Portrait of a Noob

#16

Post by [deleted] »

ivenkys wrote: post #15
silentbicycle wrote: post #8

Earlier quoted context omitted.

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…

Yup , that was my point on the "doc-comments where appropriate". Overall design of the system can/should be expressed with a good,well-written README.txt. I know UML is "supposed" to solve that problem but not for me.

[deleted]
Post reply on HN