comment your magic codes

1

Dislike

flyerhzm Posted by flyerhzm on December 19, 2010

Ruby/Rails provides a lot of magic codes, especially for metaprogramming, they are powerful, less codes to implement more functions, but they are not intuition, you should write good comment for your magic codes.

Ruby/Rails provides a lot of magic codes, especially for metaprogramming, they are powerful, less codes to implement more functions, but they are not intuition.

You may quickly write the metaprogramming to cleanup your codes, but I promise the magic codes will be strange to you after a few days, and please remember that your magic codes will not be read only by you, you have to write some comments to make your magic codes easy to read and understand.

Here are some example comments I wrote for my projects

alt text

alt text

As you seen, I not only add the comments at the top of magic codes, but also add the comments at the right side, replacing the magic codes with normal codes. It makes me much easier to understand what the magic codes do even though I haven't seen the codes for a few months. I think the other developers can also understand these magic codes intuitionally.

convention comment
related best practices:

Comments

Pito Salas Posted by Pito Salas on 2010-12-20T15:38:00Z

I totally agree; I wish I saw more of this in Ruby source code. Comments are not evil. Magic can be evil.

anonymous Posted by wentbackward on 2011-01-04T02:28:56Z

Sorry mate, but the comments on the right only make it harder to understand, except perhaps for people that don't understand the code on the left. What's the point of writing the code twice? It completely goes against everything we're trying to do nowadays. The better approach would be to understand the code on the left more and refactor it to be more readable so it stands on it's own. I think some form of documentation that explains what the magic is (or rather, what conventions are implemented), is certainly needed and the rails guides are invaluable. The magic with rails is that it actually became mainstream.

Pablo Posted by Pablo on 2011-02-08T21:11:21Z

Comments are not evil. But they are pointless if your code is well written. If you had documented the code, no comments on how to use the method would be necessary.

chucai Posted by chucai on 2011-02-17T14:03:38Z

实际的编程中，大家很少写注释。

sevk Posted by sevk on 2011-03-22T01:46:34Z

注释一定要多写.

anonymous Posted by feixiong on 2011-04-15T09:50:54Z

Whether the EOS tag is necessary ??

marsbomber Posted by marsbomber on 2011-05-04T05:48:47Z

yes, i would try to take out the magicness instead

matthewcford Posted by matthewcford on 2011-07-27T22:24:34Z

Consider using Yard or Rdoc for this kind of thing

juancolacelli Posted by juancolacelli on 2011-08-21T16:41:51Z

I think it's more readable if you put your comments before/after the "magic codes".
Post a comment

  1. Note: if you are a registered user, you can log in without input username.

    2. You may use ONLY these HTML tags to format your comment:

    <a href="" title=""> <b> <blockquote> <pre> <code> <em> <i> <strong>

    Use <pre><code>...</code></pre> for multi-line codes.

    Do not use <p> tags. Just use newlines.

Fork me on GitHub