Softpanorama (slightly skeptical) Open Source Software Educational Society

May the source be with you, but remember the KISS principle ;-) Softpanorama Search

Programming style

Old News

[Oct 14, 2001] In Defense of Not-Invented-Here Syndrome  by Joel Spolsky

Joel on Software

Time for a pop quiz.

 1. Code Reuse is:

a) Good
b) Bad

2. Reinventing the Wheel is:

a) Good
b) Bad

3. The Not-Invented-Here Syndrome is:

a) Good
b) Bad

Of course, everybody knows that you should always leverage other people's work. The correct answers are, of course, 1(a) 2(b) 3(b).

Right?

Not so fast, there!

The Not-Invented-Here Syndrome is considered a classic management pathology, in which a team refuses to use a technology that they didn't create themselves. People with NIH syndrome are obviously just being petty, refusing to do what's in the best interest of the overall organization because they can't find a way to take credit. (Right?) The Boring Business History Section at your local megabookstore is rife with stories about stupid teams that spend millions of dollars and twelve years building something they could have bought at Egghead for $9.99. And everybody who has paid any attention whatsoever to three decades of progress in computer programming knows that Reuse is the Holy Grail of all modern programming systems.

Right. Well, that's what I thought, too. So when I was the program manager in charge of the first implementation of Visual Basic for Applications, I put together a careful coalition of four, count them, four different teams at Microsoft to get custom dialog boxes in Excel VBA. The idea was complicated and fraught with interdependencies. There was a team called AFX that was working on some kind of dialog editor. Then we would use this brand new code from the OLE group which let you embed one app inside another. And the Visual Basic team would provide the programming language behind it. After a week of negotiation I got the AFX, OLE, and VB teams to agree to this in principle.

I stopped by Andrew Kwatinetz's office. He was my manager at the time and taught me everything I know. "The Excel development team will never accept it," he said. "You know their motto? 'Find the dependencies -- and eliminate them.' They'll never go for something with so many dependencies."

In-ter-est-ing. I hadn't known that. I guess that explained why Excel had its own C compiler.

By now I'm sure many of my readers are rolling on the floor laughing. "Isn't Microsoft stupid," you're thinking, "they refused to use other people's code and they even had their own compiler just for one product."

Not so fast, big boy! The Excel team's ruggedly independent mentality also meant that they always shipped on time, their code was of uniformly high quality, and they had a compiler which, back in the 1980s, generated pcode and could therefore run unmodified on Macintosh's 68000 chip as well as Intel PCs. The pcode also made the executable file about half the size that Intel binaries would have been, which loaded faster from floppy disks and required less RAM.

"Find the dependencies -- and eliminate them." When you're working on a really, really good team with great programmers, everybody else's code, frankly, is bug-infested garbage, and nobody else knows how to ship on time. When you're a cordon bleu chef and you need fresh lavender, you grow it yourself instead of buying it in the farmers' market, because sometimes they don't have fresh lavender or they have old lavender which they pass off as fresh.

A Comparative Review of LOCC and CodeCount

This paper provides one review of the comparative strengths and weaknesses of LOCC and CodeCount, two tools for calculating the size of software source code. The next two sections provide quick overviews of CodeCount and LOCC. The final section presents the perceived strengths and weaknesses of the two tools. A caveat: although I am attempting to be objective in this review, I have in-depth knowledge of LOCC and only very superficial knowledge of CodeCount. Comments and corrections solicited and welcomed.

CodeCount

The incarnations of CodeCount can be divided into two basic flavors. The first flavor, which I will dub as "Classic" CodeCount, has been in production use for over a decade. The second flavor, dubbed "CSCI" CodeCount, is the result of a set of student projects to support various "object" languages by extending Classic CodeCount.

Classic CodeCount is a relatively old and mature project. The first work on Classic CodeCount began in the late 1980's. CodeCount reflects its early origins in three important ways.

1. It is written in ANSI C, with all the typical strengths (speed) and weaknesses (lack of higher level program structuring mechanisms, etc.) of that language.

    

2. It was originally designed to provide size metric information appropriate to the kinds of languages targetted at that time (assembly languages and non-OO languages such as C and Fortran). Classic CodeCount does not employ a grammar and so has cannot reliably recognize object oriented language structures within a file, such as packages, classes, methods, inner classes, etc.

    

3. It has been used extensively by many industrial partners for over a decade, and has presumably been used to count many millions of lines of code. It can be presumed to be well-tested and reliable for the kinds of measures it produces.

Here is an example of the kind of output produced by CodeCount:

Libre Software Engineering - Tools - Other

CODECount

The CodeCount toolset is a collection of tools designed to automate the collection of source code sizing information. The CodeCount toolset spans multiple programming languages and utilizes one of two possible Source Lines of Code (SLOC) definitions, physical or logical. CODECount's license is not Libre Software as it puts additional restrictions.

cflow

The cflow command analyzes the C, C++, yacc, lex, assembler, and object files and writes a chart of their external references to standard output. Cflow2vcg converts the result of the cflow utility to a VCG format. See also Cflow2Cflow

calltree

calltree is a static call tree generator for C programs. It parses a collection of input files and builds a graph that represents the static call structure of the files.

perl_metrics

perl-metrics is intended to help perl programmers write better code by helping programmers become more aware of their coding style. In particular, one would like to know the code-to-comment ratio, the average number of lines per subroutine, and the longest subroutine.

c_count

c_count counts lines, statements, and other simple measures of C/C++/Java source programs. It is not lex/yacc based, and is easily portable to a variety of systems.

Pythius

Pythius is a set of tools to assess the quality of Python code. This is commonly done by applying different code metrics. Simple code metrics are the ratio between comments and code lines, module and function size, etc.

Free Code Graphing Project

Produces a PostScript representation of a project's source code. The fcgp comes from Rusty Russell's Linux Kernel Graphing Project (lgp)

Metrics collection tools for C and C++ Source Code

This page offers access to a collection of static code analysis tools that compute various metrics defined on C and C++ source code. The metrics are primarily size and complexity of various types (lines of code, Halstead, McCabe, etc.).

Python Cyclomatic Complexity Analyzer

Perl-written script that calculates the cyclomatic complexity for Python scripts.

CodeWeb

Open source code for a wide range of software is now in abundance on the net. The goal of the CodeWeb project is to data mine

QSM Source Code Counter Links -- list several programs for counting lines, statements, etc.

Tutorials

The Elements of Programming Style ~ Usually ships in 24 hours

Brian W. Kernighan, P. J. Plauger / Paperback / Published 1988
Amazon Price: $40.74 ~ You Save: $10.19 (20%)

Was first published in 1979. Now slightly outdated. Code Complete : A Practical Handbook of Software Construction contains similar material if you want a more recent book, but this book pioneered the field. Contains an interesting discussion of how to transform the program to a better one and common pitfalls in programming. The authors have provided an useful set of tips for coding (and sometimes design). Here is a summary of the important programming style tips from Brian Kernighan's 1994 guest CS50 lecture:

• Say what you mean, simply and directly.
• Use the "telephone test'' for readability.
• Write clearly - don't be too clever.
• Don't use conditional expressions as a substitute for a logical expression.
• Parenthesize to avoid ambiguity.
• Each time you make a test, do something.
• Follow each decision as closely as possible with its associated action.
• Use the good features of a language; avoid the bad ones.
• Capture regularity in control flow, irregularity in data.
• Each module should do one thing well.
• Make sure comments and code agree.
• Don't just echo the code with comments - make every comment count.
• Don't comment bad code - rewrite it.
• Use symbolic constants for magic numbers.
• Watch out for side effects and order of evaluation.
• Macros are not functions.
• Watch out for off-by-one errors.
• Test programs at their boundaries.
• Program defensively.
• Make sure input cannot violate the limits of the program.
• Make it right before you make it faster.
• Keep it right when you make it faster.
• Don't sacrifice clarity for small gains in ``efficiency.''
• Don't stop with your first draft.

The road to better programming Introduction and chapter 1

Zlatanov (tzz@iglou.com)
Programmer, Gold Software Systems
November 1, 2001

The success or failure of any software programming group depends largely on its ability to work together as a team. From manager to members, to well-conceived, yet dynamic guidelines, the team as a whole is defined by the unison of its parts. Shattering the myth of the faultless programmer, Teodor dismantles the uninspired software group and then builds it up again into a synchronized, energized ensemble.

Welcome to a series of articles on developerWorks comprising a complete guide to better programming in Perl. In this first installment, Teodor introduces his book and looks at coding guidelines from a fresh perspective.

This is the book for the beginner to intermediate Perl programmer. But even an advanced Perl programmer can find the majority of the chapters exciting and relevant, from the tips of Part I to the project management tools presented in Part II to the Parse::RecDescentsource code analysis scripts in Part III.

The words program and script are used interchangeably. In Perl, the two mean pretty much the same thing. A program can, indeed, be made up of many scripts, and a script can contain many programs, but for simplicity's sake, we will use the two terms with the understanding that one script file contains only one program.

Goals of the book
Part I is full of tips to improve your Perl skills, ranging from best programming practices to code debugging. It does not teach you Perl programming. There are many books with that purpose, and they would be hard to surpass in clarity and completeness.

Part II will teach you how a small Perl software team can be better managed with the standard tools of software project management. Often, Perl programmers embody the "herd of cats" view of software teams. Part II will apply project management tools to a small (2- to 6-person) Perl development team, and will examine how managing such a team successfully is different from the classic project management approach.

Part III will develop tools to analyze source code (Perl and C examples will be developed) and to help you manage your team better. Analysis of source code is superficial at best today, ranging from the obvious and irrelevant "lines of code" metrics to function points (see Resources later in this article), which do not help in understanding the programmer's mindset. Understanding the programmer's mindset will be the goal of Part III. Tools will be developed that help track metrics such as comment legibility and consistency, repetitiveness of code, and code legibility. These metrics will be introduced as a part of a software project, not its goal.

There is no perfection in programming, only its pursuit. Good programmers learn something new every day and continually improve their skills and technique. Rigidity and inflexibility are forever the enemy of ingenuity and creativity.

In pursuit of perfection
The most common mistake a programmer can make is not in the list of bugs for his program. It is not a function of the programmer's age or language of choice. It is, simply, the assumption that his abilities are complete and there is no room for improvement.

Arguably, such is human nature; but I would argue that human nature is always on the prowl for knowledge and improvement. Only hubris and the fear of being proven wrong hold us back. Resisting them both will not only make a better programmer, but a better person as well.

The social interactions and the quality of the people, I believe, are what create successful software teams more than any other factors. Constant improvement in a programmer's skills and the ability to take criticism are fundamental requirements for members of a software team. These requirements should precede all others.

Think back to the last time you changed your style. Was it the new algorithm you learned, or commenting style, or simply a different way of naming your variables? Whatever it was, it was only a step along the way, not the final change that made your code complete and perfect.

A programmer shouldn't be required to follow precise code guidelines to the letter; nor should he improvise those guidelines to get the job done. Consider an orchestra -- neither static, soulless performers nor wildly improvisational virtuosos (though the latter is more acclaimed). A static performer simply follows the notes without putting effort and soul into the music; the virtuoso must restrain herself from errantly exploring new pieces of the melody or marching to the beat of her own drum.

Striking a concordant tone
Code guidelines are like the written directions a musician follows -- when to come on, when to come off, how fast to play, what beat, etc. The notes themselves, to extend the analogy somewhat precariously, are the goals of the project -- sometimes lone high notes, and sometimes a harmony of instruments.

In an orchestra, there is a conductor that directs but does not tell every musician how to play, and everyone has a part in the performance. The conductor creates harmony. Because music has been around for many more centuries than the art of programming, perhaps these are lessons well worth learning. The software project manager is neither a gorilla nor a walled-off convict. She is a part of the team just like everyone else.

The guidelines presented in this series are not to be blindly extracted into an official coding policy. The coding standards in your project are uniquely yours, and they reflect your very own orchestral composition. Don't force programmers to do things exactly right, thereby creating an atmosphere of distrust and fear. You can forget about code reviews, or admission of responsibility for the smallest bugs.

Instead, present the guidelines and watch how people react. If no one adopts the comment format you like, perhaps it's a bad format. If people write without cleverness, perhaps you have been too clever in the guidelines. If the debugger you thought everyone must run is sitting in a dusty room, still packed, then rethink the need for Whizzo Debugger 3.4. Maybe everyone is happy with Acme Debugger 1.0 for a reason.

Of course, programmers can be stubborn for no reason at all, only out of reluctance to change. It's hard to convince people that 20 years of experience do not entitle them to an organized religion. On the other hand, freshly minted college graduates often lack self-confidence. Recognize and adapt to those characteristics, and to all the others of your team. Present ideas to the stubbornly experienced in such a way that they feel they have helped with it. Build up the college graduates with guidance and support until they can fly on their own.

All this, just for a few coding guidelines?
Coding guidelines are fundamental to a software team, just as direction and harmony are to music. They create consistency and cohesiveness. New team members will feel welcome and gel more quickly. Ye olde team members will accept newcomers more readily. The loss of a team member will not cripple the project just because someone can't understand someone else's code.

Keep in mind that speed is not the only measure of improvement in a program's code. Consider ease of testing, documentation, and maintenance just as important to any software project, especially for the long term. A language as flexible as Perl facilitates good coding in every stage of the software project. Although this book focuses on Perl, many of the principles are valid for other languages such as C, C++, Java, and Python.

Finally, be an innovator. Regardless of your position in the team -- manager or member -- always look for new ideas and put them into action. Perfection may be impossible, but it's a worthy goal. Innovators are the true strength of a team and without them the melody grows stale very quickly. Stay in touch with your peers; continually learn new things from them. A medium such as Usenet (see Resources) is a great place for an exchange of ideas. Teach and learn, to and from each other. Remember, there's always room for improvement. Above all, have fun, and let the music begin.

Resources

• Read more chapters of The road to better programming.
  
   
• Read Applied Software Measurement: Assuring Productivity and Quality, 2nd edition (McGraw-Hill), by Capers Jones.
  
   
• Read the Function Points FAQ, and check out the International Function Points User Group.
  
   
• Read all you ever wanted to know about Usenet.
  
   
• Read Teodor's other Perl articles in the developerWorks "Cultured Perl" series:
  • A programmer's Linux-oriented setup
  • Application configuration with Perl
  • Automating UNIX system administration with Perl
  • Debugging Perl with ease
  • The elegance of JAPH
  • Genetic algorithms applied with Perl
  • One-liners 101
  • Parsing with Perl modules
  • Perl 5.6 for C and Java programmers
  • Reading and writing Excel files with Perl
  • Review of Programming Perl, Third Edition
  • Small observations about the big picture
  • Writing Perl programs that speak English
• Browse more Linux resources on developerWorks.
   
• Browse more Open source resources on developerWorks.

About the author Teodor Zlatanov graduated with an M.S. in computer engineering from Boston University in 1999. He has worked as a programmer since 1992, using Perl, Java, C, and C++. His interests are in open source work on text parsing, 3-ti

C Elements of Style

C Elements of Style was published by M&T books in 1992. An abbrivated copy of the book is presented here.

This book covers only the C language and is a bit out dated. However it still contains a lot of good advice.

Note: The HTML conversion is not perfect. If you want things nicely formatted, get the PDF version.

Table of Contents	HTML Format	PDF Format
Chapter 1: Style and Program Organization	HTML Format	PDF Format
Chapter 2: File Basics, Comments, and Program Headings	HTML Format	PDF Format
Chapter 3: Variable Names	HTML Format	PDF Format
Chapter 4: Statement Formatting	HTML Format	PDF Format
Chapter 5: Statement Details	HTML Format	PDF Format
Chapter 6: Preprocessor	HTML Format	PDF Format
Chapter 7: Directory Organization and Makefile Style	HTML Format	PDF Format
Chapter 8: User-Friendly Programming	HTML Format	PDF Format
Chapter 9: Rules	HTML Format	PDF Format

 

Recommended Links

---

In case of broken links please try to use Google search. If you find the page please notify us about new location

Brian Kernighan

• Brian Kernighan homepage
• Why Pascal is Not My Favorite Programming Language
• Indian Hill C Style and Coding Standards
• Optimization of Computer Programs in C
• Rob Pike Notes on Programming in C
• The Ten Commandments for C Programmers (Annotated Edition)

• ***** Brian Kernighan's Programming Style Tips  a summary of a classic book

• Chapter 1 Philosophy Matters -- good rehash of programming style issues with usual for Eric Raymond doze of moralizing (could be skipped -- go directly to the second part ;-). Some point are questionable but this is an early version and it's too early to criticize it for that. for critique of Eric Raymond views on opensource see my OSS page

• GNU Coding Standards - Table of Contents

• **** Indian Hill C Style and Coding Standards --  (see C faq for the  explanation of the term "Indian Hill C style guide"). Mostly reasonable, but authors sometimes demonstrate a little bit too much zeal... For example indentation should be enforced by pretty-printer, not manually ;-)

• **** Notes on Programming in C by Rob Pike; mirror Notes on Programming in C  see also: Notes on Programming in C [.ps]

• ***+ SDM C Style Guide -- if you delete a half-dozen "fundamentalist" recommendation like avoiding global variables, continue and other "structured programming fundamentalism" nonsense, this document can be a pretty reasonable style guide...

• **** C Programmer's Notebook -- slightly outdated but insightful

• ***+ Henry Spencer's The Ten Commandments for C Programmers see also mirror site The Ten Commandments for C Programmers

• programming at ftp.cs.toronto -- an interesting collection of style-related documents including Indian Hill C style guide

• It can't happen, explains how to write programs that don't dump core [.ps]
• Notes on Writing Portable Programs in C .
• Defensive programming.

• C Programming Style in libwww

• Programming Style (book review)

• Program Identifier Naming Convention -- the idea of enhancing name with type information (probably the author is going to far, but some ideas can be reused)

• Programming assigmnets style -- an example of academic style recommendation most of which are plain wrong ;-)

• Paul's Pile of Papers

General

• Programming With Style

C and C++ Style Guides by Christopher Lott

This page offers access to many style guides for code written in C and C++, as well as some discussion about the value and utility of such style guides. This collection includes two style guides that are based on work done at Bell Labs Indian Hill (the site in Naperville, Illinois where the 5ESS digital switch is developed).

The list includes HTML, PDF, postscript, and original versions whenever possible. If you have a working formatter (either LaTeX or troff), the original versions are almost certainly the best, and the PDF or postscript versions are probably preferrable to the HTML version. But hey, this is the web, I put up the HTML versions to make browsing easy.

The documents are not listed in any particular order. All postscript and original version are gzip'd to save transmission time (for you) and disk space (for me).

• Original Indian Hill guide with annotations by H. Spencer
  15 pages; HTML, PDF, troff
• Indian Hill C style guide, as amended at UofT, UW, and elsewhere
  28 pages; HTML, PDF, troff
• C++ coding rules from Ellemtel (Swedish Telecom) by Mats Henricson and Erik Nyquist.
  68 pages; HTML, PDF
  This was expanded into a book called Industrial Strength C++ by Mats Henricson and published by Prentice-Hall in 1996 (ISBN 0131209655). Although it is no longer in print, the text is available here: http://hem.fyristorg.com/erny/industrial/
• C++ style guide from Wildfire Communications
  About 46 pages; HTML
• C++ Coding Standard by Todd Hoff
  About 64 pages; HTML
• Document about C++ code inspections by J. Baldwin
  21 pages; PDF
• Notes on programming in C by Rob Pike
  5 pages; HTML, PDF
• C porting guide by A. Dolenc, A. Lemmke, and D. Keppel
  22 pages; HTML, PDF, LaTeX
• Ten Commandments for C programmers by Henry Spencer
  Original (1 page): HTML, PDF, troff; and annotated (several pages): HTML
• Henry Spencer's writings on code stealing, reuse
  11 pages; HTML, PDF, troff
• A paper about checking for failure codes by Ian Darwin and Geoff Collyer, a paper presented at the January 1985 Usenix conference.
  19 pages; HTML, PDF
• Words of wisdom from Henry Spencer and Geoff Collyer about the appropriate use of #ifdefs, a paper presented at the Summer 1992 Usenix conference.
  13 pages; PDF
• Tim Ottinger's rules for naming variables and classes.
  About 7 pages; HTML
• Cstyle document from ESA, Australia
  About 9 pages; plain-text
• Coding standard from the GNU people as of 10 Feb 89
  About 5 pages; plain-text
• Some discussions about style documents (from Usenet, 1993)
  About 8 pages; plain-text
• More discussion about style documents (from Usenet, 1989)
  About 6 pages; plain-text
• Linux Kernel coding style from Linus Torvalds.
  About 5 pages; plain-text

Finally, if you would like a quick way to develop your own style guide for C, C++, or Java, Sven Rosvall offers a style-document generator. His page lets you make some choices about various constructs, and the generator builds a HTML document for you.
http://www.qualitygeneration.com/cgi-bin/genCodeStd.pl

Broken links:

• NASA Development Coding Standards and Style Guide [broken link]

• Recommended C Style and Coding Standards

• C Style and Coding Standards

• www.scs.ryerson.ca -- Programming with style

• Thoughts on C Style

• Checklist for Code Reviews

Programming abilities

Table of contents for journalcogp , volume40 , issue2 , part0 -- online papers

Cognitive Psychology

Psychological Online Documents - Cognitive and Experimental Psychology

AI, CogSci and Robotics Cognitive Science, Psychology, Linguistics -- good collection of links

Cognitive Psychology Research Group

• Genius Explained. Cambridge: Cambridge University Press, 1999
• The Psychology of High Abilities. London: Macmillan, 1999
• A Teacher’s Guide to the Psychology of Learning, Second Edition. Oxford: Blackwell, 1999
• Principles of Abilities and Human Learning. Hove: Psychology Press, 1998
• IQ in Question: the Truth about Intelligence. London: Sage, 1997
• Howe, M.J.A., Davidson, J.W., & Sloboda, J.A. (1998) Innate talents: Reality or myth? Behavioral and Brain Sciences, 21, 399-442.