Self Documenting Code

[peewee_RotA]

I'm a big fan of self documenting code, but I'm curious. What are your thoughts about the following statements from a blogger?

• If I see someone has written an event, I try to get rid of it – this goes 2x for custom events.
• If I’m working on someone’s production code and I see comments, I refactor and delete them.
• I rarely use conditionals.

http://blog.alanklement.com/2009/11/27/data-structors-with-as3-linked-list/

After thinking the question over, now consider it in the prism of this article applying to AS3/Flex programmers (script jockeys). Is this line of thinking even possible in a scripting language without full OOP support?
(missing features include: no function overloading -not oop but still relevant-, no overriding properties, no extensions, no multiple inheritance)

[quadz]

I'm a big fan of self documenting code, but I'm curious. What are your thoughts about the following statements from a blogger?

• If I see someone has written an event, I try to get rid of it – this goes 2x for custom events.
• If I’m working on someone’s production code and I see comments, I refactor and delete them.
• I rarely use conditionals.

Since I'm not familiar with the specific technology I'll skip the first item, as I don't know the pros/cons associated with whatever is meant by an 'event' in this context.

I'd probably rephrase the other two as:

• If I can identify way to clarify the code to make a given comment superfluous (and thus removable), I'll likely do so.
• I tend to aggressively search for ways to minimize the use of conditionals in logic I'm writing.

As it happens I was just applying the latter to some loop-termination logic (the loop needs to flush data periodically but also at the very end - and I want both handled by the same logic), which reminded me of this thread.

The way I see it, the fewer conditional paths through the code, the fewer edge cases to test -- aka. less opportunity for a bug to be lurking in some infrequently executed code path.  So I regard the benefits associated with minimizing such paths to be worth some effort on my part.


Regards,

quadz

[peewee_RotA]

Totally agree with that. I read some info on "Simple Code" a year ago. I can't remember the source. (probably some book called Simple Code)

The idea itself is not new, but the way of looking at a problem was pretty cool. The premise is that complicated solutions are easy to create. However complicated solutions are hard to modify and support. So if you can work your problem out using a simpler method (not always more efficient) then code becomes more self documenting and easier to modify.

[kren.Z]

First off, I'm a shitty programmer so take everything i say with a grain of salt.


From the article " his implementation is a little overkill for many of the simple things I do.".

I think a lot of that has to do with the language itself. AS3, similar to Java,  is a strictly typed language. This is why I hate C++, just waaaay too much overhead. I think Python solves this problem perfectly. You're putting more focus on solving the problem at hand rather than on the language itself.

Come to think of it, I really don't know the true benefits of strictly typed languages. Runtime error checking? performance improvements? can't be that significant


Second, these guys are doing image galleries. The code in the article is a good implementation, but you can imagine dealing with some goon who starts doing multiple inheritance and other "Good Language Practices" for such a simple problem.


I just started a course that focuses on robotic cars (http://www.udacity.com/overview/Course/cs373). What's interesting is that you really don't start programming until about week 2, which emphasizes the importance of solving problems with computers rather than solving programming language problems.

[reaper]

•If I can identify way to clarify the code to make a given comment superfluous (and thus removable), I'll likely do so.
•I tend to aggressively search for ways to minimize the use of conditionals in logic I'm writing.

If the comment deciphers the code in human terms, I'd see "cleaning it up" as a waste of time

I'm not sure what you mean by the second thing, you mean less jumping between locations of instructions, whether you are using loops, gotos or conditionals?  functions call other functions based on things, so I think you'd wanna pick your battles there

as for the original post, some people can reverse engineer binary files, so you can do anything with whatever language, but different tools for different things would be more efficient to say the least

[quadz]

•If I can identify way to clarify the code to make a given comment superfluous (and thus removable), I'll likely do so.
•I tend to aggressively search for ways to minimize the use of conditionals in logic I'm writing.

If the comment deciphers the code in human terms, I'd see "cleaning it up" as a waste of time

I've lost track of the number of times I've wasted time on a wild goose chase because I believed what a comment was saying about the code, only to find out the comment was lying.  The comment may have been correct at one point in the lifetime of the system, but over time the system changed and the comment became inaccurate.

I suppose one could say, "oh, well, ideally someone should have kept the comments up to date!".  But the practical reality is code is less likely to lie than comments.  Thus, I'd rather see intent expressed in code rather than as comments wherever possible.

If a concrete example helps, I'm saying that instead of this:

Code: [Select]

  def handle_batch_image_result(rowid, local_path, box_size, params)
    ephemeral_catalog_id = params["cid"]
    local_result_dir = File.dirname(local_path)
    item_id = (ephemeral_catalog_id << 40) | rowid  # pack catalog id and row id
    flags = ImageRequest::FLAG_THUMBNAIL
    result = [item_id, local_result_dir, flags, box_size]
    @window_svc.msg(:cache_result, result)
  end

I'd rather see this:

Code: [Select]

  def pack_catid_rowid(ephemeral_catalog_id, rowid)
    item_id = (ephemeral_catalog_id << 40) | rowid
  end

  def handle_batch_image_result(rowid, local_path, box_size, params)
    ephemeral_catalog_id = params["cid"]
    local_result_dir = File.dirname(local_path)
    item_id = pack_catid_rowid(ephemeral_catalog_id, rowid)
    flags = ImageRequest::FLAG_THUMBNAIL
    result = [item_id, local_result_dir, flags, box_size]
    @window_svc.msg(:cache_result, result)
  end

Granted, this is a fairly trivial example.  But broadly applied, this is an important concept.

I'm not sure what you mean by the second thing, you mean less jumping between locations of instructions, whether you are using loops, gotos or conditionals? 

I'm talking about structuring the code to eliminate special cases where possible.  I'd rather have every line of code in a function executed every time, rather than parts of the function that only get executed under certain conditions.

This isn't always possible, but when it is possible I think the benefit makes it worth pursuing pretty aggressively.

For example, instead of this: (pseudo-code example)

Code: [Select]

  while data_remaining
    if buffer_full
      flush_buffer
    end
    add_data_to_buffer
  end
  flush_buffer  # make sure final data is written out

I'd rather see:

Code: [Select]

  while data_remaining
    add_data_to_buffer
    if buffer_full || done
      flush_buffer
    end
  end

In the former, there's a conditional code path that only gets hit in the buffer_full condition.  If you're testing out your program and you never happen to hit the buffer_full case, that code isn't being executed.  Depending on your testing methodology and how rare the buffer_full case is, that code may never get executed until you've shipped the product and one of your customers tries something unusual.

By contrast, in the latter structuring, any time you process any data at all, all the code will be executed, because the same code is used to handle the buffer_full condition and also the final flush.

Note, however, that when dealing with real code, it usually takes a little more brainpower to arrive at the latter structure.  Thus, the forumer structure is unfortunately rather common.


Regards,

quadz

[peewee_RotA]

I suppose one could say, "oh, well, ideally someone should have kept the comments up to date!".  But the practical reality is code is less likely to lie than comments.  Thus, I'd rather see intent expressed in code rather than as comments wherever possible.

Generally this is true, but there are some tools or methods to help yourself become better at keeping comments up to date. One of the coolest ones is how Resharper will update function header comments for you to at least match return values and parameters.

The other method I've used is a modification of what was described to me as "bullet tracer".

The bullet tracer method is pretty simple and probably as common. You first define on the whiteboard your classes and their methods to solve the given problem. (The amount of specific implementation logic worked out is irrelevant). Then you start at an entry point and stub out the methods that you know you are going to need. Since you are not really putting in any implementation logic, the names of the methods naturally become very self documenting.

My modification to this is to always work out the logic for the entry point, then starting at the entry point I describe the logic using only comments and finish stubbing out any functions and classes that I need. I then convert the comments into code, and usually only leave the comments that describe an algorithm or an un-obvious decision.

Future changes are made similarly. I revisit the existing comments, confirm them with code, then I write my comments to describe what I need to do. After that I follow the same method of turning comments into code and leaving things that I see useful.

[QwazyWabbit]

In C you usually only comment exceptional cases or work-arounds for some issue or other. My all-time favorite useless comment is "this is a hack". Shit yeah! Now explain why you had to do it dipshit. But the explanation is not forthcoming. Sigh.

These are the kinds of comments that need to be removed. Along with the hack that made it necessary.

[peewee_RotA]

In C you usually only comment exceptional cases or work-arounds for some issue or other. My all-time favorite useless comment is "this is a hack". Shit yeah! Now explain why you had to do it dipshit. But the explanation is not forthcoming. Sigh.

These are the kinds of comments that need to be removed. Along with the hack that made it necessary.

I feel like C is a language that needs more comments than others. It's not naturally self documenting IMO.



I am guilty of that "This is a hack" comment. I use it as a search token for myself so that I know to come back and replace it. Although that rarely happens, it helps out when I need it. I always try to explain it further in comments though.