
How to Be a Programmer: A Short, Comprehensive, and Personal Summary (2002) [pdf] - mtmail
https://www.doc.ic.ac.uk/~susan/475/HowToBeAProgrammer.pdf
======
anon1253
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 didn’t make that much of a
difference in the grand scheme. It’s just sitting on your ass and either do as
you’re told or come up with something better, like 90% of all work. Software
is just like any other job, and chances are it is completely stupid like most
other desk jobs out there. And if not, the same general skills apply. Stop
feeling like it is difficult or even special.

~~~
pkghost
No other profession has quite the same capacity to transform itself.

Like blacksmiths, programmers are capable of building tools that not only
change the way they work but enable new kinds of work to be done, often by
making previously onerous tasks trivial, and giving the individual a much
large potential impact.

Unlike blacksmiths, programmers can share their inventions with the entire
industry in the blink of an eye. So the rate at which the programmer's
toolchain can change is indeed special.

Sure, it can also be glorified plumbing at times, but I think we think
programming is special because it is.(Not that that will continue to be the
case forever.)

~~~
sjg007
You should watch Primitive Technology on youtube:
[https://www.youtube.com/channel/UCAL3JXZSzSm8AlZyD3nQdBA](https://www.youtube.com/channel/UCAL3JXZSzSm8AlZyD3nQdBA)

------
rightbyte
"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 to and prefer to read the code
anyway_ ... More importantly however, is that the code and the documentation
cannot get our of sync if there is no documentation. The source code can at
worst be wrong and confusing. The documentation, if not written perfectly, can
lie, and that is a thousand times worse"

This is such baloney. I understand that many programmers want barriers of
entry to their chair at the office but rationalizing it is self-deception.

The author is essentially saying to write strcmp() "self-explanatory" rather
than the a black box description like:
[http://www.cplusplus.com/reference/cstring/strcmp/](http://www.cplusplus.com/reference/cstring/strcmp/)

strcmp() is useless without knowing what the return values mean and reading
the code to figure it out is way more time consuming than reading the docs.

~~~
theoh
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.

~~~
rightbyte
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.

~~~
theoh
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_...](https://en.m.wikipedia.org/wiki/Lions%27_Commentary_on_UNIX_6th_Edition,_with_Source_Code#"You_are_not_expected_to_understand_this")
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.

~~~
rightbyte
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/...](https://minnie.tuhs.org/cgi-
bin/utree.pl?file=PDP7-Unix/cmd/cat.s)

V2 of Unix had no comments in cat. [https://minnie.tuhs.org/cgi-
bin/utree.pl?file=V2/cmd/cat.s](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.

------
porphyrogene
I read through some of the Beginner section that I thought seemed
inappropriate for beginners and found a number of grammar and punctuation
errors. While trying to navigate the file I found that the page numbering
shown in the Table of Contents is off by two pages. His advice on "difficult
people" sounds like he is talking about a single, specific person but is doing
so in a vague way and expects that to function as actionable advice. That
seems like a common pattern as I look back on the rest of the section. He
talks about what were probably specific events or situations in a very non-
specific way and by doing so falls short of providing useful insight. It would
be more effective to write about the details than to try to adapt the story to
a common experience.

~~~
walshemj
And your point is?

~~~
jimmaswell
What is yours? The point of the comment you're replying to is obvious. They
provided some specific criticism of the material.

~~~
walshemj
I was using a rhetorical device - all I saw was an anonymous complaint about
grammar and no real substantive critique with know examples?

------
dcx
This appears to be an updated and edited version of this document:
[https://github.com/braydie/HowToBeAProgrammer](https://github.com/braydie/HowToBeAProgrammer)

------
juangacovas
I find the "learn to debug" chapter refreshing. I've seen a lot of new hires
on web development area who simply don't interactively debug anything,
sometimes even don't log, just because "printing" is enough. IMO we need more
bootcamps on fundamentals.

------
dang
Lots of previous discussions but not for four years:

[https://hn.algolia.com/?query=How%20to%20Be%20a%20Programmer...](https://hn.algolia.com/?query=How%20to%20Be%20a%20Programmer:%20A%20Short,%20Comprehensive,%20and%20Personal%20points%3E30&sort=byDate&dateRange=all&type=story&storyText=false&prefix=false&page=0)

------
machinesmachine
I think comments under this article are more important than linked work itself

------
chj
warning: This is not short.

------
robertAngst
>Short

Proceeds to have 40 pages

~~~
durovo
Most guides are at least 200 pages long. 40 pages is not long in comparison

~~~
robertAngst
>Most guides are at least 200 pages long.

>Most

Most?

You mean sometimes.

------
sifoobar
I honestly don't even understand the title, write code?

How to become a better programmer makes some kind of sense, though the short
answer is similar: write more code.

Which leaves no time to fill the ether with noise, so it's a double win.

How does this end up on the front page in the first place?

~~~
Gonkero
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.

~~~
natalyarostova
My math skills improved the most when I stopped obsessing over studying the
right things, or finding the right textbooks, and just constantly solved
problems.

~~~
crooked-v
Being a mathematician and solving already-theoretically-understood math
problems are two things that often don't have a lot of overlap.

~~~
natalyarostova
Yeah fair.

