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.

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.

Tests are also both code and documentation.

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

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.

"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.

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.

very good point :)

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.

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.

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.

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

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.

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

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.

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.

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.

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.

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

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.

Edit: Not project documentation, strictly code comments.

  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"

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

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

  sillyMisspelledDellSOAPIdentifier = "DuplicateAssets"

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

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

    if i["DupilcateAssets"]

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

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.

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.

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

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
  }

  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)
  }

  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)
  }

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.

function disambiguateRecordsByGroupID() {

    recordsSortedByTime = Data.load()

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

    print(results)

}

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.

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.

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