

Self-Commenting Code - palish

Consider this programming style:<p><pre><code>  for each function,
    - first write out its algorithm in comments,
    - then implement that.
</code></pre>
It seems like that programming style can result in higher-quality code with fewer bugs.<p>As an example, let's implement a simple "ends_with?" string utility function.  The function takes two strings and returns whether the first ends with the second:<p><pre><code>  bool endsWith( const char* haystack, const char* ending )
</code></pre>
Following our new programming style, we first write out its implementation in comments:<p><pre><code>  bool endsWith( const char* haystack, const char* ending )
  {
    // find the end of [haystack] and [ending].

    // if [haystack] is shorter than [ending] then it can't end with [ending], so return false.

    // walk backwards through both strings.

      // if a character differs, return false.

    // otherwise, [haystack] ends with [ending], so return true.
  }

</code></pre>
Pretty straightforward.  And now we can implement the function in an equally straightforward way:<p><pre><code>  bool endsWith( const char* haystack, const char* ending )
  {
    // find the end of [haystack] and [ending].
    const char *haystackEnd = haystack;
    const char *endingEnd = ending;
    while( *haystackEnd ) 
      haystackEnd++;
    while( *endingEnd ) 
      endingEnd++;

    // if [haystack] is shorter than [ending] then it can't end with [ending], so return false.
    if( haystackEnd - haystack &#60; endingEnd - ending )
      return false;

    // walk backwards through both strings.
    while( endingEnd != ending )
    {
      // if a character differs, return false.
      if( *endingEnd != *haystackEnd )
        return false;

      --endingEnd;
      --haystackEnd;
    }

    // otherwise, [haystack] ends with [ending], so return true.
    return true;
  }
</code></pre>
What is interesting about this style is that the result will usually be simple to read and understand.  The key is to write out the function's comments <i>first</i>, not last.  Is this a common programming style?<p>A friend of mine uses this technique in his game engine to great effect.  The engine's source code is beautiful, mostly because each algorithm is simple and can be understood by reading clear English.
======
asimjalis
Why not break them out into separate functions? Use the comments to name these
functions. Each comment is a hidden function. Also this will reduce code
duplication? For example,

    
    
      char* findEnd( char* s)
      {
        while( *s ) s++;
        return s;
      }
      
      bool endsWith( const char* haystack, const char* ending )
      {
        // find the end of [haystack] and [ending].
        const char *haystackEnd = findEnd(haystack);
        const char *endingEnd = findEnd(ending);
      
        // Etc.
      }

------
goofygrin
When I'm writing a block of code, I tend to do something like this. I pseudo
code the algorythm and then write the code.

I tend to remove my comments though and they normally aren't 100% correct by
the time I'm done and have refactored (heck, a lot of times the comments
become the code/called method names).

And then you assume that the comments are kept around/up to date when a bug is
fixed or an enhancement is added.

------
xenoterracide
what do you do with a rewrite or bugfix, feature adding? more importantly what
do you do when you know what you want it to do but not how you are going to do
it?

------
pixpop
I think that's what used to be called design.

