Author Topic: Self Documenting Code  (Read 3784 times)

Offline peewee_RotA

  • Brobdingnagian Member
  • ***
  • Posts: 4152
  • Hi, I'm from the gov'ment and I'm here to help you
    • View Profile
  • Rated:
Self Documenting Code
« on: February 21, 2012, 04:15:29 AM »
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)
« Last Edit: February 21, 2012, 04:18:03 AM by peewee_RotA »
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
GOTO ROTAMODS (rocketgib)
GOTO ROTAMAPS (fireworks)
HappyFriar- q2server.fuzzylogicinc.com
 Tune in to the Tastycast!!!!  http://dna.zeliepa.net

Offline quadz

  • Loquaciously Multiloquent Member
  • ****
  • Posts: 5352
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #1 on: February 22, 2012, 04:42:27 AM »
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

« Last Edit: February 22, 2012, 04:51:30 AM by quadz »
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
"He knew all the tricks, dramatic irony, metaphor, bathos, puns, parody, litotes and... satire. He was vicious."

Offline peewee_RotA

  • Brobdingnagian Member
  • ***
  • Posts: 4152
  • Hi, I'm from the gov'ment and I'm here to help you
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #2 on: February 22, 2012, 04:54:56 AM »
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.
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
GOTO ROTAMODS (rocketgib)
GOTO ROTAMAPS (fireworks)
HappyFriar- q2server.fuzzylogicinc.com
 Tune in to the Tastycast!!!!  http://dna.zeliepa.net

kren.Z

  • Guest
Re: Self Documenting Code
« Reply #3 on: February 22, 2012, 06:07:16 AM »
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.
« Last Edit: January 28, 2014, 01:24:01 PM by krenZ »
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus

Offline reaper

  • Opulent Member
  • *
  • Posts: 2872
  • Nice night for a walk, eh? - Nice night for a walk
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #4 on: February 22, 2012, 06:25:58 PM »
Quote from: 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'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
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
VaeVictus "reaper is a lying sack of shit and ragequit then had, probably slugs, come alias and beat me, wasnt even the same person playing OBVIOUSLY, accuracies basicly doubled, and strategy

Offline quadz

  • Loquaciously Multiloquent Member
  • ****
  • Posts: 5352
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #5 on: February 22, 2012, 07:37:37 PM »
Quote from: 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

  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
"He knew all the tricks, dramatic irony, metaphor, bathos, puns, parody, litotes and... satire. He was vicious."

Offline peewee_RotA

  • Brobdingnagian Member
  • ***
  • Posts: 4152
  • Hi, I'm from the gov'ment and I'm here to help you
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #6 on: February 23, 2012, 03:20:32 AM »
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.
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
GOTO ROTAMODS (rocketgib)
GOTO ROTAMAPS (fireworks)
HappyFriar- q2server.fuzzylogicinc.com
 Tune in to the Tastycast!!!!  http://dna.zeliepa.net

Offline QwazyWabbit

  • Carpal Tunnel Member
  • ******
  • Posts: 1371
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #7 on: February 23, 2012, 07:41:58 PM »
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.
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus

Offline peewee_RotA

  • Brobdingnagian Member
  • ***
  • Posts: 4152
  • Hi, I'm from the gov'ment and I'm here to help you
    • View Profile
  • Rated:
Re: Self Documenting Code
« Reply #8 on: February 24, 2012, 03:22:31 AM »
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.
  • Insightful
    Informative
    Funny
    Nice Job / Good Work
    Rock On
    Flawless Logic
    Well-Reasoned Argument and/or Conclusion
    Demonstrates Exceptional Knowlege of the Game
    Appears Not to Comprehend Game Fundamentals
    Frag of the Week
    Frag Hall of Fame
    Jump of the Week
    Jump Hall of Fame
    Best Solution
    Wins The Internet
    Whoosh! You done missed the joke thar Cletus!
    Obvious Troll Is Obvious
    DO YOU EVEN LIFT?
    DEMO OR STFU
    Offtopic
    Flamebait
    Redundant
    Factually Challenged
    Preposterously Irrational Arguments
    Blindingly Obvious Logical Fallacies
    Absurd Misconstrual of Scientific Principles or Evidence
    Amazing Conspiracy Theory Bro
    Racist Ignoramus
GOTO ROTAMODS (rocketgib)
GOTO ROTAMAPS (fireworks)
HappyFriar- q2server.fuzzylogicinc.com
 Tune in to the Tastycast!!!!  http://dna.zeliepa.net

 

El Box de Shoutamente

Last 10 Shouts:

 

|iR|Focalor

November 06, 2024, 03:28:50 AM
 

RailWolf

November 05, 2024, 03:13:44 PM
Nice :)

Tom Servo

November 04, 2024, 05:05:24 PM
The Joe Rogan Experience episode 223 that dropped a couple hours ago with Musk, they're talking about Quake lol.
 

Costigan_Q2

November 04, 2024, 03:37:55 PM
Stay cozy folks.

Everything is gonna be fine.
 

|iR|Focalor

October 31, 2024, 08:56:37 PM
 

Costigan_Q2

October 17, 2024, 06:31:53 PM
Not activated your account yet?

Activate it now! join in the fun!

Tom Servo

October 11, 2024, 03:35:36 PM
HAHAHAHAHAHA
 

|iR|Focalor

October 10, 2024, 12:19:41 PM
I don't worship the devil. Jesus is Lord, friend. He died for your sins. He will forgive you if you just ask.
 

rikwad

October 09, 2024, 07:57:21 PM
Sorry, I couldn't resist my inner asshole.
 

Costigan_Q2

October 09, 2024, 01:35:05 PM
Et tu rikwad?

Please don't feed the degenerate lies of a sexually-perverted devil-worshipping barking dog like Focalor.

Show 50 latest
Welcome, Guest. Please login or register.
November 10, 2024, 02:09:03 PM

Login with username, password and session length