On Sun, Mar 16, 2008 at 10:34 AM, David Brown <[EMAIL PROTECTED]> wrote: > On Sun, Mar 16, 2008 at 09:23:51AM -0700, Paul G. Allen wrote: > > > 8 spaces is too much, it takes too much space on the line. It forces the > > eye to move and look around the page too much. 2 is too few as it does not > > separate the indented structure enough from the surrounding structures. 4 > > seems to be optimal as it provides good separation, does not force a lot of > > eye movement, and does not take up too much space on the line. > > > > (Ref.: McConnell, Steve; Code Complete; Microsoft; <http://www.cc2e.com/>) > > But, it's just a bunch of arbitrary numbers. Why should I care what Steve > thinks is "too much" or "too little" spacing. Other people obviously have > differing opinions. Change the numbers to different values, and you will > get a different set of people arguing loudly that they are absolutely > right.
Ah, but what is the size of those different sets? A LOT of people use 4. I see it more often that 2 which I see more often than 8. If you restrict your observations to "Linux kernel developers" then, of course, 8 rules. But across a large range of code on Linux, Windows, Java, Python, etc. 4 appears to dominate. Why? I think it dominates because it has a balance to it. Not too much. Not too little. If some degree of balance isn't desirable then we'd see 1 and 10 more often. I think lack of appreciation for balance is one of the most underrated philosophies in software development. People get fascinated by extremes. Let's make our indentation really tiny (2). No, let's make it really HUGE (8). Let's make our language really huge (Perl). No, let's make it really tiny (LISP). I'm rarely happy at the extremes. So KISS is "Keep It Simple Stupid", but since I'm not stupid and I don't like extremeness for the sake of extremeness, I need another acronym. BLIS: BaLance Is Sublime Maybe that L ruins the official "acronym" status--I don't know--but I like it! > > Each class, method, file, function, or module should have a comment header > > describing what it's supposed to do. (Not what it does, but what it's > > *supposed* to do.) It should have a list of input parameters and exit > > parameters (returns). > > I have so rarely seen a list of parameters that was useful, I now actively > argue against putting them in list form. Most of the time, they end up as > an English description of the types of the variables. I would much rather > see a piece of prose that mentions the arguments. I think people like the > lists because they don't have to think about it. I agree that prose that mentions the arguments is more succinct and useful. > I think a lot comes from people writing their comments to the wrong > audience. Really, there need to be two comments for a function. In > languages with separate declarations, this works well: > > - One comment should be for the person who wants to use the function. > The should not care how it is implemented, but what it does and how > they should be using it. > > - The other comment, which should be near the function, should be written > for someone who wants to understand the implementation or modify it. > It should be assumed this person is fluent in the language, and should > describe the stuff that isn't obvious. Sounds reasonable. > > At times I've seen them (and written them) with references to calling and > > called functions/methods, but these days a code browser (and many IDEs) > > will tell you that. On occasion the method/function itself may need a > > comment here or there to explain why something is done that may not be > > obvious (e.g. - some quirk of the machine it was written for causing the > > engineer to write some little piece of code that may not normally be > > there). The code itself should be self-documenting such that a lot of > > comments throughout is not necessary. > > A good rule is that a comment should never describe anything that is > specified in the code. The programming language is a more exact way of > describing these things. How about this: It should specify the "why"? Because code already specifies the "how" but in some cases the code can almost be an encryption of the "why" that motivated the developer to write that snippet. I find myself sprinkling "why" comments in my own code if, when reading it several months later, it takes too long to comprehend. > > With code that is maintained by a team of engineers, comments as to who > > changed what, when, and why are necessary, and in most cases, mandatory. > > Often a simple changelog at the top of the file is not enough to adequately > > explain the changes made. > > Or, get a [EMAIL PROTECTED] revision control system. Any comment, anywhere, > that > describes a change or it's purpose tells me that the revision control > system is broken. If other people don't have access to your revision > control system, get a distributed revision control system. > > Cluttering the code with information that doesn't matter to the reader just > makes it difficult to read. A decent system will have a "blame" or > "annotate" command, and it is very easy to figure out what change put a > piece of code in place, and read a detail of the description. I can then > also look at what it was changed from, instead of just the partial > information of what it is like now. I agree. On my current contract we have to mark our changes in the code with ticket number, name, date and summary description of the ticket. But that info is already in the checkin comment and now our code is littered with this crap everywhere. > We've actually recently just had to add an additional requirement to a > contractor to forbid them from putting these kinds of comments in code. Poor guy probably picked up the habit at his last place. -Chuck -- http://cobra-language.com/ -- [email protected] http://www.kernel-panic.org/cgi-bin/mailman/listinfo/kplug-lpsg
