From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: (qmail 13958 invoked by alias); 23 Apr 2010 22:06:23 -0000 Received: (qmail 13949 invoked by uid 22791); 23 Apr 2010 22:06:22 -0000 X-SWARE-Spam-Status: No, hits=-1.9 required=5.0 tests=BAYES_00,T_RP_MATCHES_RCVD X-Spam-Check-By: sourceware.org Received: from VLSI1.ULTRA.NYU.EDU (HELO vlsi1.ultra.nyu.edu) (128.122.140.213) by sourceware.org (qpsmtpd/0.43rc1) with SMTP; Fri, 23 Apr 2010 22:06:18 +0000 Received: by vlsi1.ultra.nyu.edu (4.1/1.34) id AA23872; Fri, 23 Apr 10 18:12:54 EDT From: kenner@vlsi1.ultra.nyu.edu (Richard Kenner) Message-Id: <11004232212.AA23872@vlsi1.ultra.nyu.edu> Date: Fri, 23 Apr 2010 22:18:00 -0000 To: mfwitten@gmail.com Subject: Re: Why not contribute? (to GCC) Cc: gcc@gcc.gnu.org, lopezibanez@gmail.com In-Reply-To: <4bd214d9.101abc0a.75e9.2b3b@mx.google.com> References: <4BD1ED48.4050107@oracle.com> <11004231910.AA22539@vlsi1.ultra.nyu.edu> <4bd214d9.101abc0a.75e9.2b3b@mx.google.com> X-IsSubscribed: yes Mailing-List: contact gcc-help@gcc.gnu.org; run by ezmlm Precedence: bulk List-Id: List-Archive: List-Post: List-Help: Sender: gcc-owner@gcc.gnu.org X-SW-Source: 2010-04/txt/msg00602.txt.bz2 > My rule of thumb: good code is largely self-documenting. Maybe. But good code can't give the SPECIFICATIONS of a function, just it's implementation. I don't believe there's any substitute for putting comments in front of a function to say what the function is SUPPOSED to do. That's only in the mind of the writer and needs to be written down. Also, an important thing to put in comments is WHY something is done the way it is and (more importantly) why it ISN'T done another way. No amount of good quality code can contain that information. > [2] to understand what any block of code is > doing (this follows from [0] and [1], and > essentially promotes maintaining the proper > level of abstraction for each such block). You need to understand, what a block of code is doing, what it's supposed to do, and why it's doing it. In some cases, the latter two parts are obvious, but when they're not, there's no substitute for proper comments. > Following these ideals basically forces a programmer to > write code as though it is meant to be read and understood > by *others*; that's crucial to being able to work within > a team (especially one distributed around the world). Indeed!