[nghst]

I think the occasional "header" comment is useful, even in cases where the code is obvious, i.e.

   // do blah blah
   obvious_thing;
   obvious_thing;
   obvious_thing;
   obvious_thing;

   // do something else
   obvious_thing;
   obvious_thing;
   obvious_thing;
   obvious_thing;

Even though none of the lines really need documentation, having the comment ensures that you can quickly jump in when you come back later.

This is really useful in something like drawing code.

[wdewind]

Here's a better solution:

  function main()
    do_blah_blah();
    do_something_else();
  end

  function do_blah_blah()
    obvious_thing;
    obvious_thing;
    obvious_thing;
    obvious_thing;
  end

etc..

[fournm]

This isn't always possible in every case--it's not too hard to imagine a lot of trivial assignment all going on at once, that isn't immediately obvious what it is or why on earth it exists.

  //really bad example, just something really repetitive
  function main()
    // set up month boundaries
    janStart = blah;
    janEnd = blah;
    // ...
    decStart = blah;
    decEnd = blah;
  end

where it's not too hard to imagine many languages without great pointers needing to keep that inline to avoid making all of those variables global. In some (hopefully most) cases just better design in general can get around it, but I wouldn't always count it out immediately.

edit: oops, formatting fail.

[wdewind]

Return an array or hash?

[overcyn]

Or just write a comment...

[wdewind]

In comparison to refactoring into functions, adding comments offers:

-similar level of abstraction -much worse readability -much worse modularity

[jeremiep]

It should be pointed out that with inlining, both versions are exactly the same at runtime.

Descriptive function names never lie, comments often do.

[masklinn]

> Descriptive function names never lie

Beg pardon[0]?

    function _utf8Encode(&$arr){ 
      for($i=0;$i<(count($arr['parameters']));$i++){ 
        $arr['parameters'][$i]= $arr['parameters'][$i]; 
      } 
    } 
    function _utf8Decode(&$arr){ 
      for($i=0;$i<count($arr['parameters']);$i++){ 
        $arr['parameters'][$i]= $arr['parameters'][$i]; 
      } 
    }

Or[1]

    public static string ReturnEmptyStringIfNullElseValue(string value) {
        if (value == null) {
            return "";
        } else {
            return value.ToString().Trim();
        }
    }

[0] http://thedailywtf.com/Comments/There-and-Back-Again.aspx

[1] http://thedailywtf.com/Articles/Common-Functions,-not-Common...

[jeremiep]

I stand corrected. Thank god I never have to deal with such code!

[wschroed]

> Descriptive function names never lie, comments often do.

Description function names lie just as much as comments. For example, I have run into cases in the wild where things like "get_item()" create database entries before returning a value. Yes, side effects are evil, etc etc, but the point is that at some point, somebody maintained the code and did not update every use of get_item() to now be get_and_or_create_items_if_it_is_sunday(). In rare cases, I have seen them at least update the local documentation.

[collyw]

What's to say a function gets "fixed" without updating the name, in the same way that comments will not get updated? I see it would be less likely in a function, but not impossible.

[zimbatm]

And now you have three places to look at instead of one.

[wdewind]

How do you figure?