logoalt Hacker News

ofrzeta • yesterday at 12:38 PM • 1 reply • view on HN

Quite the praise by Grady Booch:

"There are only a few comments in the version 1.0 source code, most of which are associated with assembly language snippets. That said, the lack of comments is simply not an issue. This code is so literate, so easy to read, that comments might even have gotten in the way."

"This is the kind of code I aspire to write.”

Replies

crazygringo • yesterday at 3:06 PM

> the lack of comments is simply not an issue

I'm looking at the code and just cannot agree. If I look at a command like "TRotateFloatCommand.DoIt" in URotate.p, it's 200 lines long without a single comment. I look at a section like this and there's nothing literate about it. I have no idea what it's doing or why at a glance:

  pt.h := BSR (r.left + ORD4 (r.right), 1);
  pt.v := BSR (r.top + ORD4 (r.bottom), 1);
  
  pt.h := pt.h - BSR (width, 1);
  pt.v := pt.v - BSR (height, 1);
  
  pt.h := Max (0, Min (pt.h, fDoc.fCols - width));
  pt.v := Max (0, Min (pt.v, fDoc.fRows - height));
  
  IF width > fDoc.fCols THEN
    pt.h := pt.h - BSR (width - fDoc.fCols - 1, 1);
  
  IF height > fDoc.fRows THEN
    pt.v := pt.v - BSR (height - fDoc.fRows - 1, 1);
Just breaking up the function with comments delineating its four main sections and what they do would be a start. As would simple things like commenting e.g. what purpose 'pt' serves -- the code block above is where it is first defined, but you can't guess what its purpose is until later when it's used to define something else.

Good code does not make comments unnecessary or redundant or harmful. This is a myth that needs to die. Comments help you understand code much faster, understand the purpose of variables before they get used, understand the purpose of functions and parameters before reading the code that defines them, etc. They vastly aid in comprehension. And those are just "what" comments I'm talking about -- the additional necessity of "why" comments (why the code uses x approach instead of seemingly more obvious approach y or z, which were tried and failed) is a whole other subject.

➕ show 3 replies