Hacker News Reader

Comment by jheriko | Hacker News Reader

> This author advocates little if any comments, documentation etc.

I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code.

Some optimised code might be really incomprehensible without commnets, but its the exception rather than the case. By far my biggest use of comments is to highlight inadequate or rushed code that should be revisited later (i.e. TODO: or HACK: rather than NOTE:).

Don't get me wrong - design and documentation is useful in practice as well as being the 'theoretical ideal' that I think should be striven towards. Diving in and making a mess to fix stuff or diverging from an original design is bad in theory - in practice it is a necessary evil with tight deadlines or when rescuing a project that is already in a seriously bad state - or even when the original design was naive or even impossible because it came from an inexperienced or otherwise inadequate source.

View on HN

>>I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code.

I'm very much of the opinion that you are very much of the wrong opinion.

"Good code self-documents" is a myth. Most programmers have trouble coming back and reading their own code, much less other programmers' codes. Comments and documentation written in spoken language ensure that the code can be understood much more quickly and efficiently and any misunderstandings are prevented.

The fatal problem with the notion that the code is the documentation is the fact that the code only tells you what the code does, as opposed to what it's designed to do. How do you know a behavior you observe by reading the code isn't a bug which is going to be fixed next week? Or an arbitrary implementation detail that isn't guaranteed? That is what docs and interfaces and specs are for. "The code is the documentation" only works if the code is immutable.

Tests tell you what the intended behaviours are. If there is no test then it is not intended.

Tests are also both code and documentation.

> Tests tell you what the intended behaviours

Or, you know, the design can also. If you're into having that.

This is a rather extreme opinion. I find tests to provide less value than they create most of the time. I think regression tests and integration tests are quite valuable. The former are created after the fact, and the later are often so difficult to do correctly that they are never made. Of course, this difficulty is the same reason why they are valuable.

Nonsense. When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bugs.

well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it.

If people could just get over this documentation phase that programming went through in the 80's and 90's due to languages containing obtuse syntax and being so low level you had to hold a dozen things in your head at once (I'm thinking of you COM) - but in this era, with languages that operate at a high level of abstraction the era of documenting the code is over.

"The code is the documentation only works if the code is immutable."

that's actually backwards. If you want to stand any chance of changing the code then it should be readable and well structured, not well documented.

I'm skeptical. How do you know what's intended behavior and what isn't if you don't know why the code is structured the way it is? Understanding what it does is necessary but not sufficient. You risk introducing more bugs if you don't understand why the code does what it does.

"well chosen function and variable names tell you the intention, if it's modular enough then it will all make sense when you read it."

The two hardest things in computer science are concurrency and naming things. Oh, and off-by-one errors.

If the code doesn't match what's intended, it's most likely because the original implementator misunderstood it, or didn't think of a particular edge case - and thus the comments won't reflect that as well.

You look at code to determine what exactly the system does, but in order to determine what exactly the system should do, you need to look at the users needs or the business process, the code+comments can't tell you that.

Any public API should be documented. I can spend all day reading your code trying to code against your API, or I can read the API docs & be on my merry way. When/if there is a bug, I can fix it so it adheres to the specified purpose/pre/post conditions.

> Any public API should be documented.

very good point :)

What I'm looking for in comments is the underlying assumptions and the "why" that was flying around in the author's head when they were doing it.

> When you read the code you need to know what it does, not what the programmer had intended, then, and only then, will you stand any hope of fixing bugs.

I'm talking about being a user/caller of code, not attempting to fix it. Of course you need to know the innards if you're going to fix it, but needing to know all the implementation details in order to even call a piece of code is counter-productive. It's needlessly time-consuming and it violates the concept of separation of concerns.

"Most programmers have trouble coming back and reading their own code"

Hogwash! maybe if you're writing assembly code or similar low level language, but one of the express benefits of high level languages like python, scala, ruby etc is that they read (to a competent developer) like english (or whatever your native tongue might be)

Maybe you and "most programmers" you know don't write decent code, but I can easily read others or my own code if its well written. The last thing I want is a bunch of comments everywhere. I am all for the occasional comment (as an exception) because my eye will be drawn to it, but in general, unless your code sucks, it should perfectly legible without the need for excessive comments and documentation.

You haven't worked in anything important, anywhere, ever.

Also if you think that you'd always remember why you did something, at some point in time, for all given circumstances, you haven't lived long enough.

> Maybe you and "most programmers" you know don't write decent code, but I can easily read others or my own code if its well written

You really aren't that good as you think. Your problem is you grossly overestimate your capabilities and achievements. We all were there, most of us outgrow it. You will too at some point.

I've done a lot of digging through other people's code, in general the only comments I've found helpful are those that explicitly call out defective code, and those that provide links to external references.

Writing clear code is the only hope for the poor maintenance programmer, your carefully written comments probably aren't worth the effort.

thats really harsh.

playing the experience card is poor form and fallacious - also it wouldn't surprise me if that commenter is speaking from extensive experience.

i don't mention my 20 years of experience or background as a AAA game dev having touched every speciality with experience in high volume web and database environments, financial data quality software, language compilers and interpreters or anything like that... its next to worthless vs. what i can do, demonstrate or explain.

Yes it is harsh, in the same style of the parent comment.

Actually you're wrong on the experience card, for only one reason. What I mentioned is experience gained that everyone will gain, just by staying long enough in the game. Not because, I am super cool and worked in positions that few people can work.

It's the same thing, like when we were teenagers and we thought that we were right in every freaking thing and our parents just responded "wait until you grow up". Well they were right in most of the things, weren't they? Were they super smart? Was it relevant if they were? Nope, they just stayed long enough in the "game".

Same thing here.

i dunno, i like your example of parents. my experience of that was definitely learning just how naive and unprepared for everything they were...

i don't rate experience highly at all. quality of experience and what you learn from it is what adds value to that 'time served'.

plenty of old men will still dance even though they have been terrible at it for 50 years. they have had a lot of practice, but they still suck. there are ample examples like this

I agree with what you say and I find it quite orthogonal to what I said :)

You also gave an interesting example. Dancing is a specialized activity. Thus specialized talent and/or quality experience is required. But not all people go dancing. So I wouldn't quite include it in the set of common experiences that most people will go through in their lives.

I think your last paragraph is generic enough, we can use it as a reply to your comment:

You really aren't that good as you think. Your problem is you grossly overestimate your capabilities and achievements. We all were there, most of us outgrow it. You will too at some point.

Most programmers have trouble coming back and reading their own code, much less other programmers' codes

Really? I was just poking through some code I wrote several years ago looking for something I may re-use and I didn't have any trouble figuring out the intention by reading the (largely) uncommented code.

Pure coincidence. Like those random unimportant memories that get stuck with us, but we don't know why.

When you work in really large projects, which are not hobby projects, with specs you don't even understand the reason of their existence, it is impossible.

For example I have many experiences similar to what you described, yet today I couldn't remember why I did something in a code fragment I wrote last week.

That's why you'll see all great programmers sharing similar stories. Otherwise you'd be superhuman.

Pure coincidence my friend.

I guess it could be pure coincidence. But I'm going to chalk it up to the fact that I go out of my way to have well-factored code that uses intention-revealing names and isn't too clever for its own good.

The choices that you make when writing code really do matter.

All things you mentioned are considered given, for someone that is an above average programmer.

Yet in large projects, with lots of people, with many interconnected modules, clear code and concise variable naming is not enough.

That's why we have documentation that describes the general architecture and comments for the code parts that aren't so clear cut.

Some problems have many solutions, with different levels of advantages and disadvantages. To think that all people understand or know the solutions and the choices pertaining to them, is of course naive.

To think that you, as a person, would choose the same path at different instances of time, is just entertaining. You are not the same person you were last year, or even last month.

Thus, good comments along with clear and concise code is the only way to go.

I've had this discussion a couple of times, but have failed to identify any pristine examples of essential documentation 'in the wild' myself. I'd like to know of a couple - I'm sure they are out there.

Edit: Not project documentation, strictly code comments.

Example from real-world code I've written:

  if tag in tag_list:
    data[u"Tag"] = tag
    try:
      if i["DupilcateAssets"] is not None:  # not a typo - misspelled in Dell SOAP response
        data[u"Error"] = "Duplicate assets returned"

Would you want to debug that without the comment?

This is a great example of a comment that should (or even must) be there.

If something doesn't work the way it should and it's beyond your control, comment it.

Gladly:

    sillyMisspelledDellSOAPIdentifier = "DupilcateAssets"
    if i[sillyMisspelledDellSOAPIdentifier] is not None:

But this is largely a comment disguised as a variable name, and is no more or less likely to stay up-to-date as a comment. If the Dell Identifier were to ever be changed to "DuplicateAssets", you're just as likely to have

  sillyMisspelledDellSOAPIdentifier = "DuplicateAssets"

as the original might have

  if i["DuplicateAssets"] is not None:  # Not a typo...

And your method replaces one line of code with two.

Comments have problems, but they solve problems too. They're not evil.

Agreed - I'd really appreciate coming across that one. It probably isn't the definitive example I'm looking for though.

Why not just:

    if i["DupilcateAssets"]

is there some Python subtlety I am missing?

In python some things evaluate as false in an if or boolean conversion (0, an empty list/tuple/set/dict/user_defined, an empty string "", and more). None evaluates as false as well, but is still distinguishable from the rest.

In ruby you likewise sometimes need to use object.nil? because nil and False are both "false-ish".

some comments are very useful, this is a great example

I tend to have the "comments are an apology" mindset, where I will write a comment to apologize if something is partially implemented, counter-intuitive, driven by a byzantine external requirement, or an ugly workaround to someone else's bug.

Those can totally be essential, as they will save someone (your future self, maybe) from attempting to refactor them to something simpler/cleaner that won't actually work.

| any misunderstandings are prevented

If only this were the case. Comments are frequently wrong- they were either wrong from the beginning, unhelpful, or never updated when code was changed. Whenever I find myself writing a comment, it is typically because I just wrote bad code. Sometimes, bad code is necessary; most of the time, its better to get rid of the comment and the bad code.

Ultimately, comments are not sufficient; you have to read the code anyway. Comments can only be useful in the regard of recording the intent of the author.

it being a myth is massively at odds with my experience. i'm also sure that i have data and experience... also that i can quantify why it is easy to read to some degree with logic (but measurement is king).

i know i'm fortunate to be very good at reading other people's code so my view is probably biased - its feedback i constantly get - i've never worked on a codebase where i can't contribute meaningfully on day one even when its of quite a poor quality. i've found myself explaining people's own code to themselves more than once too...

i've worked with lots of programmers and trawled through many code bases old and new... by far the easiest code for me to read is fairly devoid of comments with sensible variable names, lots of whitespace and descriptive function names and using procedural logic or sensible (not excessive) amounts of OO. hungarian notation i can take or leave...

comments don't hurt... documentation doesn't hurt, but more than once i've seen pretty disgusting code with a big comment above it explaining what it does where if they had just named variables properly and split the code into decent functions the comment would have been needless. a classic case is something which looks like:

void HandleProcessing()

{

    /// ... insert 1000 lines of code

}

which should be

void OptimiseMeshForRuntimeRendering()

{

    RemoveDuplicateVertsFromVertexBuffer();

    SplitIndexBuffersSoIndicesAre16Bits();

    OptimiseIndexOrderingForCacheEffeciency();

    PerformValidationChecks();

    WriteOptimisedDataToDisk();

}

that code requires zero comments or documentation imo it tells you what it does and how it does it... sure its a crude example i just conjured and there is some bad practice there if you take it literally (what data am I throwing around? there should be function parameters...), but i'm not afraid to say that if you struggle to read code like this then you are just not very smart. maybe the concepts (index buffer, cache) need explaining, but thats not what comments are for thats for Google, Wikipedia, hardware and library specifications and generally just knowing enough to be competent in your domain.

comments i like are this:

void OptimiseIndexOrderingForCacheEffeciency()

{

    /// use the k-cache optimisation algorithm, this has been measured to work on test1.mesh only

    // imagine code here...

}

what i never want is a huge blob of comment explaining the algorithm and burying the fact that its effectiveness in this scenario has only been measured in a special case.

its shocking how many programmers are able to produce difficult to read 1000s of lines of code functions and forget the most basic principles of good, simple procedural programming, despite how familiar they may be with design patterns, OO or functional principles, CS theory, complexity bounds etc.

advice i constantly have to give and feel i never should: use functions. name them properly. use good variable names. don't write huge comments. refactoring is a lot quicker and easier than you imagine (and removes technical debt!). don't be afraid - source control will save you.

don't mistake the plethora of terrible programmers and lack of good example code for a sound principle being mythical...

EDIT: wtf is up with the formatting in this box? i see the help link now... but screw that i'm lazy

Well written code covers the what and the how. The why is what you need to be covering with code comments. This is for the inevitable time when the "simply not so smart" developers has to fix errors in the absentee guru's code.

I'm very much of the opinion that good code self documents, and excessive use of comments and documentation is a crutch for bad code.

We obviously hear this quite a lot, but I think it's inaccurate - it's bad comments and documentation that are a problem, and comments in particular are often most prolific when they're bad. Comments and documentation often suffer from rot, in that they are not kept current with the code and end up being out of date in short order.

But the fact that comments and documentation can be out of date is a reason to do them better, rather than throw them away. I'm one of those people who typically codes "comment first" - writing a simplified english overview of the steps I expect to take, implementing each of them using real code, and taking a final pass to trim or expand comments as required. So I might start with:

  function doit(){
    // Load data from the input
    // Get the correct records
    // Search for the correct field
    // Output the results
  }

This is followed by implementation:

  function doit(){
    // Load data from the input
    records = Data.load()

    // Get the correct records
    records.uniquify(function(e) { return e.group_id })

    // Search for the correct field
    results = records.map(function(e) { return e.timestamp })

    // Output the results
    print(results)
  }

We've now got stupid redundant comments of the type that cause problems. Rule of thumb for me is to decide if the statement in the comment can be trivially deduced from the code immediately following it. If it can, then the comment can go. If there's some additional assumption—perhaps about side effects or properties of data which might not be immediately obvious—then the comment can be expanded to include this information. So we might end up with something like the following:

  function doit(){
    records = Data.load()

    // Disambiguate records by looking at the group id - records will
    // always be sorted by time, so we can do this to make sure we
    // only get the first in a given group.
    records.uniquify(function(e) { return e.group_id })

    results = records.map(function(e) { return e.timestamp })
    print(results)
  }

Obviously not real code, but you get the point.

In general, I find that working on "self-documenting" codebases is actually rather frustrating - especially when I'm coming in on a new project. There's an absolute load of implicit knowledge about software systems that's contained within the code, and while it should be exposed and made explicit wherever possible, it's sometimes not practical - meaning that "self-documenting" code often seems anything but.

thanks for the detailed reply, this is an example of an 'okay' comment, but its still not really needed imo. you can fix this with variable and function names:

function disambiguateRecordsByGroupID() {

    recordsSortedByTime = Data.load()

    results = recordsSortedByTime.map(function(record) { return record.timestamp })

    print(results)

}

ExceptThatNobodyWantsToTypeDisambiguateRecordsByGroupID20Times. (No, IDE can only help you so much. You still lose valuable screen estate for browsing source code when we have excessively long names.)

Not to mention you only captured half of the parent's comment (the "why" of the function), so it should really be something like disambiguateRecordsByGroupIDBecauseRecordsAreAlwaysSortedByTime.

yeah, i missed a whole line of code as well :)

there should probably be a reasonable limit to the length of a name... the IDEs are great, but even without them copy-paste is pretty universal and safe for identifiers.

To get rid of comments, you've now hard-coded the algorithm into every call to `disambiguateRecordsByGroupID`. What happens if something changes and you need to disambiguate records by something other than group ID? It seems like a short comment is a pretty small price to pay for some additional robustness.

  records.SortedBy(:time).DisambiguateBy(:group_id)

Reply on news.ycombinator.com