[tjeerdnet]

This is an ever ongoing discussion between two kinds of programmers (documenting and non-documenting). Just decide for yourself or your team what works best. I myself like to even document other people's code after I see what the method does if the method isn't speaking for itself. If I am developing I want to see in my IDE when adding an existing method, a popup which tells me quickly about what the method does and the arguments it has and what it returns. Instead of (everytime) having to jump to the code to see what it does.

Just one simple (real life) example:

  public String convertText(String text) {
   return text.toUpperCase();
  }

This method is already named wrong in my opinion and should be refactored to something like convertTextToUpperCase to understand what it does without having to document. But if your methods get more complex I think a little comment on top of the method describing what's going on really cannot harm. Especially if the code is difficult to read for new people.

The point is in the end to keep the documentation in sync with the code and that takes indeed some effort. I myself always make documentation for a method in Java-doc style, so only above the method, if it's more complex than a simple getter/setter-method. I always tend to think in terms of the official Sun Java API-documentation, which I use(d) so often to know how all the classes/methods work, that it might also make my own code more readable/understandable when I or someone else has to work on my code if I have documented it. Inside the method code I try to comment little to not.

@snowwolf: I agree, but it's just an example to show that a method name should speak for itself

[snowwolf]

Just to comment on your example, that method shouldn't exist as it adds no value to the codebase - it is purely redundant code. Especially if you were to rename it to convertTextToUpperCase.

The only situation where the method would make sense is if you wanted to be able to change the implementation in the future (TitleCase, LowerCase etc.), in which case a better renaming would be covertTextForDisplayInTitles (i.e. Use the method name to comment why we need to convert the text). That has the added benefit of also telling you what the method does in your IDE just from its signature.

[collyw]

I was thinking about this recently, and wondered how other people think of this. Working in a high level language like Python, you can do quite a lot in one line, for example in a list comprehension.

Should a "productive" one liner be put in a separate method / function with meaningful name, or better a comment beside it?

I personally find short methods often decrease code readability, as you constantly have to jump around, and can't read anything from top to bottom.

[Robin_Message]

> I personally find short methods often decrease code readability, as you constantly have to jump around, and can't read anything from top to bottom.

In general, if you have to jump into every method call to understand a method that calls other methods, the names are bad – probably too short and don't state intention.

[peterwaller]

My approach is frequently to "name" a complicated list comprehension by shoving it into a one or two-liner closure function in the current scope. Then you don't have to jump miles and the code which uses it becomes readable.

[collyw]

So what is the advantage of this approach over having a comment beside it? Sounds slightly more complex to me.

[peterwaller]

Because comments can lie.

Also, it can be harder to express the generator in a useful way in English than the code itself if the code is well written.

The purpose is to make the code as clearly self describing as possible. I would only do it if it made the code read more like a human language and remove too much complexity from one place.

[henrik_w]

Well named short methods lets you read the code on a higher abstraction level. I usually jump into methods to see what they do the first time I encounter them. Later on, the name (if well named) should tell me what it does, so I don't have to wade through the details of how it does it. That's part of what I'm getting at in "7 Ways More Methods Can Improve Your Program" http://henrikwarne.com/2013/08/31/7-ways-more-methods-can-im...

[marcosdumay]

Well, I can really say what it should be...

But I put one-liners in a function when the one-liner is hard to read or too error prone (missing a detail won't lead to a compiler error, but to a bug).

[lmm]

"Cannot harm" is a fallacy. Every additional comment adds a maintenance burden.

Sometimes comments are worth the cost, but they should be a fallback to a fallback - ideally, the code should be self-explanatory. If that's not possible, unit tests should explain the usage and functionality - they're better than comments because the build system enforces that they're updated when the code changes. Only if you can't do that either should you resort to a comment.

[informatimago]

As it is, it looks indeed quite dubious.

But if it had a specification comment added, it may be perfectly justified.

Remember, in programming, there's no problem that can't be solved by one additionnal level of indirection.

Here we have one level of indirection. What's not clear, is what problem it solves. This is what the comment should tell, or better, the name of the method. But perhaps we're in a context where converting things is the natural thing to do, and in this specific case, the convertion of text is a mere upcasing. Probably the conversion of numbers or the conversion of arrays will involve more work. Notice how I imagine (but leave unwritten) some specifications to justify this code. In a program those specifications should not be left unwritten.

[einhverfr]

Well, I think the code needs to be clear enough that you don't want to document unnecessarily. In general, I think code contracts should be documented, as restrictions on solutions that programmers may need to be aware of. But comments are not a substitute for clear code.