On: The Most Important Code Isn't Code

[humbledrone]

The documentation example for the multiplex() function seems like massive overkill to me. The most informative part of the documentation comment is the line that starts with "Duplicate some text..." So why not just name the function duplicate_text() and be done with it? The arguments could be documented similarly, by naming them "text" and "num_duplications".

I don't think I'd need an 11 line comment to tell me what this definition did:

  def duplicate_text( text, num_duplications )
    text * num_duplications
  end

In fact, I might prefer NO comment, because comments can become out of date and misleading, whereas the code always tells the truth.

[sparky → humbledrone]

Not to mention the fact that the word "multiplex" already has a meaning, and it has nothing to do with concatenating duplicates of a string. Unless the function name is intended to be parsed as "multiple 'X'".

[arethuza → sparky]

Rather ironic that the function "multiplex" as "multiple x" is included in an article that says:

"If you don’t have an absolute clarity in the code you’re pushing, it rears its head by way of bugs, confused coworkers, and slow code."

That's the single most confusing function name I've seen in a while.

[shasta → humbledrone]

Well, comments serve a purpose. For example, if you checked that function into my codebase, I might comment thusly:

    def duplicate_text(text, count):
        """humbledrone, you effing moron, just inline
           the effing astericks"""
        assert False

[holman → humbledrone]

That was pulled from the TomDoc spec- it was designed to demonstrate TomDoc, not the code. Having an overly complicated implementation makes explaining the documentation side of things a bit more difficult. :)

[humbledrone → holman]

Ah, I see, it's an example of how to, not when to. :)

[kjmclark → holman]

But "TomDoc is a mentality". What the heck is "TomDoc" anyway? The author says it's a mentality, but since when do mentalities come with specs? As far as I can tell, it's an example of a function spec that's so badly written that it needs a huge comment to explain it. Lousy name, lousy parameter names, no statement of what it returns, no actual return, etc. Maybe the author just needs a language that declares returns and some practice at naming variables/functions?

[nightski → holman]

But that is a good point you make :) Is it maybe not the documentation that matters so much but the semantics communicated through the code itself?

Documentation is important, its just how its done today that bothers me. I have been reading the book "Computational Semantics with Functional Programming" and it has been quite intriguing. I would highly recommend it.

[cema → humbledrone]

Even in such a small function comments may serve a useful purpose. For example, they could describe edge cases, when applicable ("a null text is considered an empty string" versus "a null text is an error", or "a zero number of duplications returns an empty string" versus "...returns a single text" and so on).

[johnl → humbledrone]

For a senior coder, comments may feel redundant but for the junior coder, it helps. If they can't comment the program from beginning to end, they haven't thought the logic through enough to write clean code. And what I like about well written comments, it's easier and faster to either modify or have someone else "step in" with the coding project if necessary, and use to explain to a non-technical manager where you are and what you are doing.