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

How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

doc.ic.ac.uk

Post reply on HN
Print view View original

51–58 of 58 posts

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#51

Post by ken »

rightbyte wrote: post #49

"When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I’ve ever known hold a universal sentiment: write self-explanatory code and don’t document code except in the places that you cannot make it clear. There are two good reasons for this. First, anyone who needs to see code-level documentation will in most cases be able…

Even more importantly, the documentation is the contract. Most languages (and especially C) aren't nearly precise enough to declare a function's complete contract using source code. How would you know if strcmp had a bug, if there were nothing that said what it was supposed to do?

Without documentation, you're left with merely: the code is supposed to do whatever it happens to do right now. Systems like this are terrible to work on. At best, you have to verify O(n) call points across the entire code base whenever you touch any function. At worst, that interface is already public, and you can't ever "fix" anything.

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#52

Post by theoh »

rightbyte wrote: post #49

"When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I’ve ever known hold a universal sentiment: write self-explanatory code and don’t document code except in the places that you cannot make it clear. There are two good reasons for this. First, anyone who needs to see code-level documentation will in most cases be able…

No, you have misunderstood. This statement refers to documentation in the form of comments in source files. You are referring to the documentation of interfaces (e.g. manual pages in Unix) which is definitely required.

A gnarly function in C will sometimes be impractical to fully 'comment'. English is too verbose and imprecise compared to the code. But, in particular, inserting uninformative comments that explain simple statements (statements that can be clearly understood by reading the line of code) is a known rookie mistake. It can lead to a case of not being able to "see the wood for the trees"—how the code works is still obscure, but every line has a literal translation in the accompanying comment.

Googling "don't comment code" brings up a number of articles and blog posts discussing this issue. One thing people sometimes say is that comments should explain 'why', not 'what', the code does, e.g. an explanation of what the algorithm is doing, where necessary, rather than a description of each programmatic operation. That kind of comment is like a gloss on what the function is doing, or a conversational explanation of the procedure that the code implements.

Again, this is not about documenting interfaces.

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#53

Post by rightbyte »

theoh wrote: post #52
rightbyte wrote: post #49

"When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I’ve ever known hold a universal sentiment: write self-explanatory code and don’t document code except in the places that you cannot make it clear. There are two good reasons for this. First, anyone who needs to see code-level documentation will in most cases be able…

No, you have misunderstood. This statement refers to documentation in the form of comments in source files. You are referring to the documentation of interfaces (e.g. manual pages in Unix) which is definitely required. A gnarly function in C will sometimes be impractical to fully 'comment'. English is too verbose and imprecise compared to the code. But, in particular, inserting uninformative comments that explain sim…

I'm not too sure the author means about that, even though you interpretation is possible.

"When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I've ever known hold a universal sentiment: write self-explanatory code and don't document code except in the places that you cannot make it clear."

I would say eg. Doxygen style function documentation or that strcmp() doc. I linked falls under documents non-programmers wont read.

Hi is emphasizing writing "little" good documentation over "write crap nobody will read". Is it really a good advice to new programmers about documentation?

Can everyone who have spent their career cursing former coworkers that wrote too much code documentation raise their hands. Congrats you were working in heaven.

I'd say when in doubt, write comments. 'How', 'why' and 'what' ... and 'when' and in what order. But that's a matter of taste of course.

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#54

Post by torgian »

Retric wrote: post #32
theonemind wrote: post #11

Earlier quoted context omitted.

Eh. Most major centers of power have large computing resources changing how they do things. Wal-Mart, for instance, as a basically non-tech company, leveraged computers for stocking and supply chains and became a culture-chaging retail giant. Computers have made their way into cars, and even toasters. We have high frequency trading (done by computers) majorly affecting markets. I could probably go on like this for a…

Most professions have already changed the world. Air conditioning for example dramacily changed how and where people work and play. Plumbing has dramatically reduced the spread of disease. The older professions are so integral to society it’s hard to thing of a world before agriculture or fishing. Give it 200 years and programming will probably be thought of as accounting. Well paid and nessisarily, but hardly revolu…

Salaries have been stagnating because companies refuse to raise the salaries, along with ever increasing inflation. Your 100k job was worth less than a dollar back in 1980, due to inflation.

Programmers should be making closer to 200-300k per year; but then everyone else would be making 30 or 40 dollars an hour minimum wage.

Supply and demand aren’t well matched, considering the job posting out there. But there’s a lot going on influencing all of this

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#55

Post by theoh »

rightbyte wrote: post #53
theoh wrote: post #52

Earlier quoted context omitted.

No, you have misunderstood. This statement refers to documentation in the form of comments in source files. You are referring to the documentation of interfaces (e.g. manual pages in Unix) which is definitely required. A gnarly function in C will sometimes be impractical to fully 'comment'. English is too verbose and imprecise compared to the code. But, in particular, inserting uninformative comments that explain sim…

I'm not too sure the author means about that, even though you interpretation is possible. "When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I've ever known hold a universal sentiment: write self-explanatory code and don't document code except in the places that you cannot make it clear." I would say eg. Doxygen styl…

The idea that this advice means "don't bother documenting APIs" is a straw man which isn't worth arguing about. The "non-programmers" phrasing is misleading, I agree, but the widely held sentiment that the author was expressing is recognizably the one about comments in source files.

When the algorithm itself really needs verbose documentation, or if the code it's intended to be used for instruction (incorporated into a book, for example), there's always literate programming.

The notorious Unix comment mentioned here https://en.m.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_... is actually a good example of a situation where a comment is needed to explain the rationale of the code. At the same time, it was clear to the documenter that the situation was too complicated to be made totally clear by the comment alone (or by reading that piece of code in isolation.) That is the kind of situation in which a comment is necessary, but also inadequate. That is the difficult reality behind this advice: comments don't really work that well when you really want them to.

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#56

Post by abc_lisper »

anon1253 wrote: post #7

Okay, I’m going to be a little bit far out there. A lot of this seems to be grounded in the negative. “How to deal with x” how to “do y when z has failed”. Some of it technical and some of it interpersonal. Why have we created this sphere around programming? What makes /this/ profession so different from any other? And my believe is: nothing. It’s not hard. It’s not better. It won’t “eat the world”. Heck it probably…

I am sorry I cannot accept this cynical position

"I think that it's extraordinarily important that we in computer science keep fun in computing. When it started out, it was an awful lot of fun. Of course, the paying customers got shafted every now and then, and after a while we began to take their complaints seriously. We began to feel as if we really were responsible for the successful, error-free perfect use of these machines. I don't think we are. I think we're responsible for stretching them, setting them off in new directions, and keeping fun in the house. I hope the field of computer science never loses its sense of fun. Above all, I hope we don't become missionaries. Don't feel as if you're Bible salesmen. The world has too many of those already. What you know about computing other people will learn. Don't feel as if the key to successful computing is only in your hands. What's in your hands, I think and hope, is intelligence: the ability to see the machine as more than when you were first led up to it, that you can make it more"

-- Alan Perlis

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#57

Post by rightbyte »

theoh wrote: post #55
rightbyte wrote: post #53

Earlier quoted context omitted.

I'm not too sure the author means about that, even though you interpretation is possible. "When it comes to actually documenting code itself, as opposed to producing documents that can actually be read by non-programmers, the best programmers I've ever known hold a universal sentiment: write self-explanatory code and don't document code except in the places that you cannot make it clear." I would say eg. Doxygen styl…

The idea that this advice means "don't bother documenting APIs" is a straw man which isn't worth arguing about. The "non-programmers" phrasing is misleading, I agree, but the widely held sentiment that the author was expressing is recognizably the one about comments in source files . When the algorithm itself really needs verbose documentation, or if the code it's intended to be used for instruction (incorporated int…

Yeah OK I agree about not wielding strawmans.

Another interesting example on comments is the original implementation of 'cat'. A lot of comments.

https://minnie.tuhs.org/cgi-bin/utree.pl?file=PDP7-Unix/cmd/...

V2 of Unix had no comments in cat. https://minnie.tuhs.org/cgi-bin/utree.pl?file=V2/cmd/cat.s

It's a extreme example, but I know which one i would prefer to debug or modify.

Re: How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf]

#58

Post by sifoobar »

mixmastamyk wrote: post #8
Gonkero wrote: post #6

Earlier quoted context omitted.

Saying you'll be a better programmer if you just write code is like saying you'll be a better mathematician if you just write more math.

It’s another way to describe practice. Which is correct but not the most compelling of arguments.

Do you have any examples of methods that will get you there more effectively than practice in any discipline? Because I honestly can't think of anything.
Post reply on HN