Code Reading: The Open Source Perspective

nazarijo writes "You can usually tell someone who's been writing a lot of code by how they write code. That may sound like a tautology, but it's got a deeper meaning than that. What editor they use, what idioms they use to avoid common pitfalls, and what organization patterns they employ all tell you what kind of programmer you're meeting. When you first start writing code, so many things are inconsistent and just plain wrong that it's almost embarrassing. I know that when I look over older code that I've written I feel sheepish about it. But how do you grow as a programmer, and what really makes a good programmer beyond language familiarity?" Read on for Nazario's review of Code Reading: The Open Source Perspective, a book which attempts to instill deeper knowledge about programming than just "knowing how." Code Reading: The Open Source Perspective author Diomidis Spinellis pages 499 publisher Addison-Weslet Longman rating 7 reviewer Jose Nazario ISBN 0201799405 summary A tour of large-scale development projects from code to organization

A few books are tackling this subject, including Coder to Developer and Programming Language Pragmatics. These books don't teach you much about a particular language in the way that an introductory text would. Instead, you grow as a skilled developer by studying them and learning from them. That's one of the key things that people are talking about lately, that to be a strong developer requires more than a working knowledge of a language. It requires a familiarity with the strengths, weaknesses, and core features of a language and the base libraries to be efficient.

Code Reading: The Open Source Perspective is one of these books in this small but growing library. In it, Diomidis Spinellis takes you through a large body of code and focuses on several languages, techniques, and facets of development that differentiate strong developers from weak ones. What I like about this book is how much it covers, how practical the information is, and how much Spinellis teaches you. You wont learn a language, which is the complaint of some people who read this book, but if you know one or two you'll be a better programmer.

Perhaps one of the most telling things about the book is that it draws heavily from NetBSD source code, and features over 600 examples to make the point. Examples are often annotated using NetBSD as a reference. This makes sense, because NetBSD is a large project that's relatively stable and mature. Everything from how to define a C structure consistently and sanely to UML diagrams and build systems are covered, making this truly a developer's book. However, even Windows and Mac OS X developers will benefit, despite the BSD focus.

Chapter 1 introduces some of the basic tenets of the book, namely that code is literature and should be read as such. All too often people only read code when they have a specific problem to solve or want to get an example of an API. Instead, if you read code frequently you'll always be learning things and improving your skills. Also, Spinellis discusses the lifecycle of code (including its genesis, maintenance, and reuse), which simply must be taken into account if code is to be good. Poorly skilled developers forget these things and just slap it together, never thinking ahead.

In Chapter 2, a number of concepts basic to any programming language are covered, including the basic flow-control units common to many languages. The book focuses on C, with additional coverage given using C++, Java, and a few other things thrown in for good measure. As such, these chapters -- in fact the whole book -- focuses on concepts common to these languages but absent in some other languages, like Scheme or LISP. One neat section is called "refactoring in the small." It illustrates the real value of the book nicely, in showing you various ways to organize your code and your thoughts for various effects. Oftentimes a book will only teach you one way (which doesn't always suit your needs), and Spinellis' examples do a nice job of escaping that trap, not just here but throughout the book.

Chapter 3, "Advanced C Data Types," focuses on some language-specific matters. These are pointers, structures, unions and dynamic memory allocation, things that most people who code in C may use but only some truly understand well. Again, a somewhat basic chapter, but useful nonetheless. Make sure you read it; chances are you'll learn a thing or two.

In Chapter 4, some basic data structures (vectors, matrices, stacks, queues, maps and hash tables, sets, lists, trees and graphs) are covered. This is an important chapter since it helps you see these structure in real-world use and also helps you understand when to chose one structure over another. While Knuth, CLRS, or other algorithms and data structures texts cover these, they often do so in isolation and at a theoretical level. While their coverage is short, it's to the point and usable by anyone with a modest understanding of C.

Chapter 5, "Advanced Control Flow," the last chapter that deals with actual programming information, is another useful one. Again, short but to the point, this chapter covers things like recursion, exceptions, parallelism, and signals, all topics that have warranted their own books (or major sections in other books) but which are covered in a single chapter here. Still, seeing them side-by-side and in the context of each other and in real-world use provides some justification for the compact presentation.

The remaining chapters of the book go well beyond a normal programming book and focus on projects. These chapters complement the first bunch nicely by focusing on the organization of your code and projects. Chapter 6 deals specifically with many of the commonly identified (but rarely taught) things like design techniques, project organization, build processes, revision control, and testing. A number of things that aren't covered include defining and managing requirements for a release and their specifications, basics on how to use autoconf and automake, and instead rips through a whole slew of topics quite quickly.

Chapter 7 is sure to be controversial for some people: it covers "Coding Standards and Conventions." Some people seem to be big fans of the "if it feels good, do it" style of programming, and instead of writing sane, usable code, what they produce is buggy and messy. This chapter teaches you tried and tested methods of naming files, indentation (and how to do so consistently using your editor to help), formatting, naming conventions (for variables, functions, and classes), as well as standards and processes. The style and standards are (as you would expect) based on NetBSD, which differ slightly from GNU and Linux standards, as well as commonly found Windows practices. However, I think you'll agree that the style is readable with minimal effort, and that goal, coupled to consistency, is paramount in any standard.

Chapter 8 introduces you to documentation, including the use of man pages, Doxygen, revision histories, and the like. Also included are hints at using diagrams for added value. One thing I don't like about this chapter is the opening quote, which sets a bad precedent. It blithely suggests that bad documentation is better than none, which is highly questionable. Misleading docs can be worse than no docs at all, since someone without docs will have to dig through the code in front of them to understand it. Someone with bad docs will rely on the docs and wonder what's broken when things go awry.

Chapter 9 focuses on code architecture, such as class hierarchies, module organization, and even core features like frameworks to chose. This chapter covers a lot of material, and is, despite its size, simply too terse on many of these subjects. It serves as a decent introduction, but doesn't go very far in some places, considering the importance of the material. However, like much of the book, it's a good introduction to the topics at hand.

Chapter 10 also features a lot of good things to know. Granted, you could pick them all up with a lot of hard work and scouring for information, but it's easier to have them presented to you in a cohesive format. The chapter discusses code reading tools, things that you use to help you dig around a large body of code. One you get over a few source files, even if you have well-organized code and interfaces, many changes can require that you inspect the data path. You can do this manually, or you can be assisted with tools. Tools like regular expressions, grep, your editor -- Spinellis shows you how to make use of all of them when you write code. A lot of tools I've never used (but have heard about) are featured, and their use is demonstrated, but of course many tools are simply ignored, focusing on popular ones that will work for most people.

Finally, all of the above is brought together in Chapter 11, "A Complete Example." A small tour of a large, complex piece of code is taken (34,000 lines of Java) as the author makes changes. It's unfortunately in Java, when so much of the book focused on C (why couldn't they have been consistent examples?), but it works. The example itself could have covered a few more things, such as a proper JUnit example, but overall I'm pleased with it.

Overall, Code Reading: The Open Source Perspective is ambitious and worthwhile, both as a complement to a bookshelf of study that includes The Practice of Programming and Design Patterns, and to someone who is growing tired of books on learning a language. At times it feels like the author promised more than he wound up delivering, but it serves as an introduction to a large number of topics. You wont learn a language, and you wont be able to get as much out of the book if you don't engage it with practice, but it's a useful book to get started on the road from being someone who knows a language or two to someone who is a developer, ready to contribute to a team and work on large projects. Never underestimate the skills required to be a good developer, because they go well beyond knowing how to use a language.

You can purchase Code Reading: The Open Source Perspective from bn.com. Slashdot welcomes readers' book reviews -- to see your own review here, read the book review guidelines, then visit the submission page.

Comments

Consistency and good comments

[Neil Blender]

When I see that develop in someone, then I know they are going to the next level. When I don't see it after time, I know they will never evolve.

Re:Consistency and good comments

[shufler]

builds the frame of his project and then fills in the code. I think it really helps to think the project through before hand, build your comments and then write.

And oddly, you'll notice that a lot of the coders who do this know a large multitude of languages

This isn't odd at all. I do it myself. And I know why I do it too -- the language you use is inconsequential. If you "write" a script, you can probably use a host of languages to do the task. The key is knowing what you want to do.

Over the years I've sat and listened to many "debates" (arguments, really) about which language was better than another. I've always sat back and thought, "Who cares?" Once you can reach a point where you can visualise the solution (this includes pseudocoding it out, or at least listing what the program has to do at this point), selecting a language is irrelevant, other than considering what languages are available to you.

I'm not saying different languages don't have their strengths and weaknesses, and I'm espcially not saying they are all the same. What I am saying is that once you "write" what the program needs to do, use a programming language is as easy as literally looking up syntax and function names in a book.

This is also how proper language translators operate. They don't know entire languages, but they instead form exactly what they need to say before translating. New languages become second nature after repeated use, it's always just a matter of knowing what you want before hand.

Re:Consistency and good comments

[fireman sam]

Personally, I prefer to have my code self commented. Meaningful variable names, no "smart arse" tricks, good clear layout.

If you have to explain what a function is to do, it has not been coded very well.

Re:Consistency and good comments

[dtrent]

Personally, I prefer to have my code self commented. Meaningful variable names, no "smart arse" tricks, good clear layout. If you have to explain what a function is to do, it has not been coded very well.

Yeah but your function doesn't live in a vacuum does it? How about you write some lines up there at the top to put it in context for when I have to fix it next year.

Your Cubemate.

Re:Consistency and good comments

[Bill Dog]

You sound as if you work in the sysadmin side of the house. This is probably totally appropriate for your tasks, where you may typically need modest-sized scripts to piece together some things to, say, process a log file.

But note that there's a whole other world out there, and be careful not to fall into the PHBism of assuming that anything you don't know about must be simple. On the software engineering side, for large-scale projects, the choice of languages is not at all inconsequential, and can affect maintainability, quality, and performance. We're not handed a pseudocode design that spells everything out, and we only have to translate it into the actual language syntax. A requirement may say such-and-such shall appear alphabetically. You know what the program "needs to do", but there are choices of sorting algorithms, and data structures/containers, that have different qualities, that should be evaluated and chosen deliberately for the task at hand.

Re:Consistency and good comments

[drsmithy]

Yup, I do it all the time. But then I go through and delete all the comments, because when I'm finished, the final code explains what's going on much more eloquently than any comment I could write about it.

But does it explain *why* ?

Very true.

[gimpynerd]

This is very true. While learning a certain language I always have many inconsistanies in my code. In fact I always want to go back and change it as I progress. It just shows that experince is much more than talent.

Re:Very true.

[superpulpsicle]

Personally I hate wasting time writing a function to do something only to find out 10 days later... the language already comes with a library that does the exact same thing. Experience do count there.

comments

[PoopJuggler]

You can tell a great deal about the maturity of a programmer by the quantity, and quality, of comments.

Re:comments

[Suicyco]

This is absolutely true. The more you have worked on past software, horrible code, etc. the more you value proper commenting and documentation. Hence, the higher quality you produce, with full knowledge that it WILL be useful someday. Many times I spend just as much time carefully crafting comments and documentation, formatting the code, etc. so it reads as cleanly as possible.

I suppose it also holds that once you have surpassed the threshold of super-duper quality commenting, you get to the point of such awesome code that it documents itself, so you come full circle.

Re:comments

[Mumpsman]

Actually, what you can tell about a programmer from comments is the ability and understanding of his/her direct supervisor.
Understanding the value of good code is one thing, but insulating your developers from top-down pressure and unreasonable deadlines which force them to "slap it together" allows programmers to prosper.
If your shop is producing crap code it's because your management is crap.

Re:Comments

[jallen02]

It all really depends. Ultimately I feel that you will learn to write code that explains itself to a large degree. There are two times I ask them to make comments.

1.) The first time to comment is when you are doing something you know are not standard. Bitwise shifts to multiply, things you know are sub-optimal etc. Exceptional things that are not done how they shold be done, or are typically done.

2.) When you want to explain how a relatively large block of code is working, or an entire classes purposes. Explaining a method or a class. Or a block of code to give an idea of flow.

Another thing that I feel improves comment quality is to force them to be complete sentences. Try and keep the sentences brief and complete so that it clearly illustrates what you are trying to say without repeating. The "Do not Repeat Yourself" DRY principle applies to written communication as well as code.

If you always refer back to these simple rules you will generally have code that is easier to maintain and that the comments don't go out of date on as quickly. I really think you could write an entire book on commenting code and naming variables and organizing code flow. Good Luck and happy coding!

I will agree that developers go through phases in how and when they comment, but having someone lay out guidelines and telling you when to comment and giving you a few concerete examples makes a huge difference. For me its always about being a good leader and doing what I say. I have seen programmers come from mediocre/average just following a few simple "rules". Commenting is a huge part of it. Because if you can comment at an abstract/high level you can prove you know what the code should be doing. And if you write comments before you write the code.... ;-)

Jeremy

Re:comments

[Anonymous Coward]

You can tell a great deal about the maturity of a programmer by the quantity, and quality, of comments.

That is, the younger, less mature programmers are commenting tons and actually documenting their work because their teachers stressed how truly important it is. This is really boring. As the programmer matures, the comments decrease but the QUALITY of the comments increase, and end up being quite novel to read.

Comments

[The Amazing Fish Boy]

The amount of comments in code is interesting. It kind of starts at an extreme, then moves slowly to the middle, happy land.

If you started programming, you either chose to comment a lot, or not at all. "A lot", because you were never sure what your code was doing, and always needed the reference. Or "not at all", because you could make sense of the code very well.

Then you start your first big project. For the big commenter, he realizes after getting quite a bit of work done that a lot of time was "wasted" on comments. ("// This line increments the 'i' variable by 1".) Further, these comments seem way too obvious. For the non commenter, they get lost easily and wish they commented more.

So it goes in the opposite direction from when it started. The big commenter comments way less, and the non commenter comments way more.

Then it repeats. Eventually the programmer gets the happy medium of the right amount of comments.

This has been my experience, in my own code, and checking other people's code. Thoughts?

Re:I don't understand

[cperciva]

... you're saying that there's more to it than just getting it done?

Yes. Getting it done right.

I believe that what you are trying to say is that:

[adolfojp]

The smart man learns from his mistakes ...

... but the wise man learns from other peoples mistakes.

I guess that I am just kind of average :-P.

Cheers,
Adolfo

Use comments only when needed

[c0d3r]

I disagree when writing Java and C#. These languages are inherintley readable if you write clean, understandable code with good variable names. Comments should be used whey you implement something that you can't understand by reading the code. Its quickker for me to read clean code, and comments often get in the way and get outdated and hurt more than they help. Maintainance is the Iceburg.

Re:Use comments only when needed

[enjo13]

You couldn't be more correct. Comments are often to blame for maintainibility problems, as dangling comments can absolutely destroy the readibility of code.

I do beleive you can judge a programmer by the quality and quantity of comments.. A good programmer comments only when the code NEEDS commenting. No more, no less.

Re:Use comments only when needed

[Anonymous Coward]

Just because it's obvious what your code is doing doesn't mean it's obvious why it's doing it. Commenting is still important.

Re:Use comments only when needed

[Viking Coder]

Sure - everything works great if you are fortunate enough to start with clean code, and keep your code clean.

But the rest of us work for a living. You know, for bosses who don't "Get It." =) We have to fight for the time to keep code clean, because that time could be spent adding features instead. It can be a hard battle.

When you're in that kind of environment, comments can save your life. Or at least your ass.

Re:Use comments only when needed

[14erCleaner]

Its quickker for me to read clean code

Maintainance is the Iceburg.

It's really hard for me to nitpick spelling, but I can't help myself, so please forgive me...

A good first step in writing clean, maintainable code is to be self-aware. Many experienced programmers don't realize that they write crappy code. Honest code reviews can help, but most people don't take criticism well, and negative style comments are ignored.

(Of course, my code is perfect... :)

Re:Use comments only when needed

[AuMatar]

Whats clear to you isn't clear to me, and vice versa. Whats clear to you now won't be clear to you in 6 months, much less 12. Thats why comments are good- in 6-12 months you will understand the comment, while you might not the code. And a thrid party is far more likely to get the comment than the code.

As for comments getting outdated- thats why you update comments when you update code. If you don't do that, you're a poor programmer. Changing the code and not the comment is doing half the job.

Re:Use comments only when needed

[gnuLNX]

Sorry, but i simply disagree with you. Comments are good, in moderation. Too many comments are a bad thing. People can learn to code in such a way that the code is readable and maintainable. If you can't write code that I can read with minimial effort then you are the bad coder, and If you can't read the code I write (most of it) then you are the bad coder. I go to great lengths to make my code as self documenting as possible. Yeah it isn't always possible and that is what the comments are for. I document the hell out of my header files, but the actual code has few and far between on the comments.

Re:Use comments only when needed

[killjoe]

COmments are best when they explain WHY you are doing something, not just explaining WHAT you are doing.

For example a comment that says "we have to make exceptions for clients whose names start with A because sales promised them a price cut" is very useful when somebody is scratching their head asking why there is a goofy if statement sitting there.

Re:Use comments only when needed

[Suicyco]

That is not the commenting at fault, it is the sloppy programmers who do not update them. Code NEEDS commenting, period. In any decent sized code base, it is not at all clear WHY things are being done at times. So you can read the code, any programmer should understand the syntax and conventions being used. That is not important. What is important is a concise, clean and understandable code structure with good comments. You can NEVER guess the level of future people reading this code. Just spell it out, what is the harm? Do not be sloppy, do not be arrogant and simply engineer good clean well documented code.

The attitude that commenting is only something to be done if something isn't obvious to YOU is totally wrong and results in poor quality.

The problem with not doing this, is if its not totally obvious WHY something is being done, it may get changed to something "better" which may break things. Perhaps that particularly ugly sort algorithm needs to be there because of extensive profiling done on the code. If that isn't spelled out, somebody may stroll along and think you were an idiot for obviously using the wrong sort and ruin the performance. For instance.

ALL code NEEDS commenting at ALL times.

I can always judge a programmer by the quality and quantity of the comments. A good programmer doesn't presume to know when the code NEEDS commenting based on his totally biased opinion. It always NEEDS it. A good programmer knows what to say to make things as clear as possible.

Re:Use comments only when needed

[gnuLNX]

"And like I said- your opinion of whats readable and maintainable is NOT going to be the same as mine. It goes down to the fact that different people think in different ways,"

Very true...but yet we all seem to be able to communicate with normal langauges without to much difficutly. If you and I both understand the programming language and the problem at hand..with a well thought out design then we should be able to code in such a way that we need mnimial english...or whatever language.

Not to mention if we both have different coding styles then the whole experience turns into a learning experience since we are both forced to read more code...and in my opinion reading a lot code is almost as important as writing a lot of code if you really want to become good at it.

Anyway I am not really disagreeing with you....I think that I am simply suggesting that development should be done closer to that "ideal" environment were all designs are well thought out and documented...I suspect you are talking more about maintenance and I also understand first hand how bad it is to maintain code that was not meant to be readable without comments...yuck!

Re:Use comments only when needed

[jerky]

Just write it as

if (pw_status == ADMIN_LOCKED) {

and leave out the comment.

Re:Use comments only when needed

[boris_the_hacker]

First rule: Nothing is obvious.
Second rule: Nothing is easy.

I was in a talk the other day and someone was explaining his research. He used the words obvious and easy more times than I have fingers, just on the first slide!

Afterwards I took him to one side and explained to him that most things are obvious and easy when you have been working on them for 2 years. He agreed and re-worked his approach.

It is the same with code, it is never obvious nor easy if you are not familiar with it.

The code I write is clean, uses meaningful identifiers, remains conistent in both structure and layout (I try to be anal about it). However, going back to some code I wrote last year, I wouldn't have stood a chance of understanding it if it wasn't for the comment explaining the algorithm in the code. This isn't because it is bad code, but because it was complicated and doing intelligent tasks (I would guess complicated and intelligent tasks covers most code).

Comments are required and are useful for understanding code, providing a bigger picture. Good comments compliment well good code. This is the same for any language.

You can have bad comments, or too many comments, but if you follow the same set of basic rules for you comments that you do your code, things should be fine.

Re:Use comments only when needed

[p3d0]

Others have said why comments are important, so I'll just say this: if someone says "you can tell a great deal about the maturity of a programmer by the quantity, and quality, of comments" and you reply "nah, I don't think they're that important", what do you think that says about you?

Coding style

[tjwhaynes]

After a while working on very large projects (>1Gb source code) I've begun to find that certain things which looked fine for personal projects are serious problems when you scale up.

Most critical is managing complexity. Large, complex functions are bad - they have more bugs, they are harder to maintain, harder to bug fix (a change has more likelyhood of breaking something else). If a function has grown beyond a hundred lines of (real) code, it is almost certainly too large. If it has more than 4 levels of nesting, it is too large.

Comments also matter. It's easy to code a couple of thousand lines of fresh code over a weekend if you get in the groove. It is almost impossible to unpick it one year later if you didn't comment it as you go.

Variable and function names should be expressive. No single letter variable names! No obscure combinations of letters like words with no vowels (fnct could be function or function control, or even Function Numerical Constant Type). And personally I find that reverse Hungarian notation can be more trouble than it's worth. puiAnnoying!

Build in automatic checks on everything. If a pointer to a function should never be null, check it and stop if it is. If a variable should only have values 1 -> maxIterations, then check it. If you (or anyone else) ever breaks that assumption, the code will flag it for you.

Beyond that, nothing beats good design, especially designs where extending the original work is easy. So many designs end up as tangle knots of conflicts because they ended up trying to solve problems that the original code base never envisaged.

Cheers,
Toby Haynes

Re:Coding style

[excesspwr]

You point out some very common problems my colleagues and myself have run into and discussed many times.

Just to add some more to what you are stating. I've come to the realization that I must determine the final size of a project before starting. If, for instance, a program starts out as a simple Perl script for parsing an input file and later ends with a request for a GUI to be added and additional functionality I'm better off starting over and rethinking the final design then just pasting on the necessary changes to meet the new requirements. Otherwise, the project, although still small and maintainable over a week or two is complete chaos when revisited in say a month or two.

Comments do matter, however; it does seem over commenting is just as much of a problem as no comments or under commenting. I have been handed projects from long gone developers that have had more comments than code. While it did give insight into what they were doing it became hard to find the code amongst all the comments, even with color coding turned on. It's an artistic poetry of having the right thing to say and saying it correctly. Which I am far from doing in this post.

The automatic checks on everything that you mention, exception handling and such, should be designed into the project from the start. Grafting it on after the fact is a nightmare and I have pity for anyone that is asked to do this and especially with code that is not theirs.

A good approach to design, I believe, trumps everything though. If you can hash out truly usable requiremets and implement a good personal software process and stick to it documenting as you go the end product always seems to turn out many notches above par even for small projects. However, none of this ever seems to occur where I work. Half baked requirements and a lack of time to properly design and implement seem to be the norm.

Re:Coding style

[AuMatar]

[quote]Most critical is managing complexity. Large, complex functions are bad - they have more bugs, they are harder to maintain, harder to bug fix (a change has more likelyhood of breaking something else). If a function has grown beyond a hundred lines of (real) code, it is almost certainly too large. If it has more than 4 levels of nesting, it is too large.[/quote]

The problem with hard fast rules like that is they're frequently not right. Take a state machine for example. A simple one with 6 or 7 states will go over 100 lines, and will go over 4 nestings. Heck, you'll take one up with the loop and one with the switch alone. You can break it into functions and hide some of the nesting in functions, but when doing that you frequently end up with functions that don't make a lot of sense by themselves.

A better rule than size IMHO is the one logical operation rule. A function should do one logical operation (read a file, write a file, run a state machine, calculate something, etc). They should contain all the logic needed to do that operation plus any debug and error handling that makes sense at that level of code. They should be broken up into subfunctions ONLY if those subfunctions themselves follow the logical operation rule, and only if that logical operation makes sense outside of the context of the higher function.

Take the state machine example. If it needs to wait on a semaphore before each iteration, the wait should be its own function- waiting on a semaphore is a logical operation. The logic for each state should NOT be separate functions, they are part of the state machine and make no sense without the whole of the machine for context. Breaking them out results in harder to read code, even if you do lose the nesting. But if in case RUNNING_MOTOR you issue a stop command to the motor that probably makes sense to be its own function- how you actually stop the motor isn't part of the core logic of the machine.

I guess my point is- lines of code isn't the enemy, some things are complex and need many lines to do. Nesting isn't the enemy, some things require many loops/ifs. The enemy is a lack of clear separation of functionality and lack of clear abstraction between parts. If you have separation and abstraction, it tends to hit the optimal readability. If you don't, it will fail either because you broke it up too much (too little context) or too little (too much context).

Re:Coding style

[bloosqr]

Actually this is one of the great things about C++. If one codes in a subset of C++ (C style,
w/ local functions) and adds in auto nulled
pointers and auto bounds checking via templates
and auto memory leak checking on assignments (via
templates as well) such that those modes are on only as a compile time option you get the best of both worlds, error checking when you need it and when you are absolutely convinced that the code will work, you can turn it off and get C/Fortran
type performance..

-bloo

Re:Coding style

[Anonymous Coward]

Variable and function names should be expressive. No single letter variable names!

I agree with that for most cases. My variables are usually very descriptive, as are the functions. However, for simple counters I find that using i or j or similar works quite well. After all, everybody understands a for loop with an i index -- calling it array_index_counter or some-such is (IMHO) pointless.

Re:Cookie-cutter book?

[Anonymous Coward]

Actually, the parent is neither off-topic nor flamebait. This book can be very good (and I think I'll buy it if I can) but this reviews lacked a comparison with another "Bibles" such as "Code Complete" (a Microsoft Press book!). Code Complete was to me the book that gave me another level of programming, exactly like this "Open Source Code Complete". The problem is really with the word "open source embedded in the title...

language bias detected

[anomalous cohort]

In Chapter 2, a number of concepts basic to any programming language are covered, including the basic flow-control units common to many languages. The book focuses on C, with additional coverage given using C++, Java, and a few other things thrown in for good measure. As such, these chapters -- in fact the whole book -- focuses on concepts common to these languages but absent in some other languages, like Scheme or LISP.

Hmmm. What concepts, particularly what basic flow control concepts, are present in C, C++, or Java yet absent in Scheme or Lisp?

Re:language bias detected

[Jerf]

The author is probably referring to the way Scheme and LISP are "missing" static type checking, in much the same way I am "missing" a hole in the side of my head.

The claim that something is missing would be more compelling if they weren't "missing" it on purpose, and the trend wasn't swinging in the dynamically-typed (or, as I think of it, "value typed" as opposed to "variable typed"; whatever you do it's wrong to call it "weakly typed") language's favor anyhow.

(Variable-based-typing's only hope is that the type-inferencing languages penetrate into the mainstream before the recoginition that variable-based-typing isn't free does, that being the fundamental misconception keeping it afloat. (Once you ack. the obvious point that it is not free, and is in fact quite expensive, both in actual effort and in massively underestimated opportunity costs, you are suddenly able to consider it in terms of costs and benefits, and the cost/benefit analysis generally does not work out in its favor when done dispassionately, though there are exceptions.))

Re:language bias detected

[d1v1d3byz3r0]

If they don't exist, you can always build them in. That's the beauty of Lisp.

Off the top of my head, I can't think of any major flow control mechanisms missing from native Lisp. If they exist, I'm pretty sure there was a good reason that they don't exist in Lisp.

comments

[defile]

If the expression itself requires a comment, then it is not being expressed clearly enough. It should be rewritten.

If the expression is clear, but does not make sense in the context, appears suboptimal, or otherwise thwarts the reader's expectations, THEN I'll comment.

Real world project comments...

• We're using this byte[] array wrapper because Java won't hash identical byte arrays to the same value.
• This is in fact a bubble sort. I'd call qsort(), but it's nowhere to be found and I'm not going to implement it myself just for this. Additionally, it doesn't matter since it sorts at most 100 records, and it's called very rarely.
• Why yes, it IS a giant waste of space to represent an 8-bit value in a 16-bit quantity. But someone thought it was a good idea to leave out unsigned.
• Unlike everywhere else, here we're waiting for key-release instead of key-press because the operating environment has a race condition and posts them out of order! Go Sun!

The art of code

[achacha]

There is a lot of truth to coding style that is not necessarily related to open source. Seasoned programmers work very hard to keep naming, patterns and even formatting consistent. It makes it easier to read.

The open source angle is that the code will be viewed by many people and thus there is a greater detail to presentation, it's a form of ego stroking and seems to work quite well.

I do code reviews all the time and I can tell a novice developer from someone who has done it for a while, it's a hard thing to explain, it's like a difference between good and bad art. And just like with art, you can have decent artists and you can have great artists with very little in-between. Go figure :)

Re:The art of code

[cratermoon]

It's not that hard to quantify the differences between a novice's code and an expert's. Here are some.

1. Novice code is longer. There will be three statements when one will suffice.
2. Novice code has duplication. You'll see the same thing done two ever-so-slightly different ways in two different place. An expert will abstract out the common code and vary on the thing that changes.
3. A novice will write redundant conditions and handlers where an expert will be concise. To give a Java example, in a catch clause, checking that the exception is not null (!)
4. Novices will code for all sort of imaginative things that *might* occur in some speculative future. Expert code will contain nothing that is not pertinent to the task at hand.

Bad docs better than none

[Acius]

Having worked on some terribly buggy code with buggy docs, I'm going to suggest that even bad docs are better than none. Sure, you get burned once or twice, but you quickly learn not to trust the docs as canon. And while the docs often don't tell you what the code does, it tells you what the developer WANTED it to do, which is golden information when you're trying to debug.

Re:Code format

[Cthefuture]

I have to say that I agree with you to a certain degree.

I'll go one more step though. It's about white space. You can almost always recognize a good programmer by how clean the code looks because of proper use of white space. If the code is all crammed together and cluttered looking then you know that programmer sucks. White space does not make your code slower guys!

Note that I said this is a way to recognize a good programmers. Often experience plays a role but I see a ton of fairly experienced programmers that write ass crappy code.

I see a lot of people saying comments are also a sign but I have to disagree. Well written code is easy to read and figure out. I would much rather have nicely written code than comments. (Note that it is my job to fix other people's code so I have a lot of experience with this)

Indeed!

[kraksmokr]

After spending many years as a programmer, and writing thousands of lines of code, I have learned so much about coding that these days I find myself not writing code at all, or very little code.

As a young freshly trained programmer, you are walking around with a hammer, and a lot of things look like nails.

You think you are a badass because of the power and precision with which you hit the nails.

Then one day and you see you are building a house. And there are a lot of other people whose work is instrumental to getting the house built.

So after a while you start telling other people how to hit their nails, and before you know it, you are building entire tracts of homes.

Re:Indeed!

[sylvandb]

After spending many years as a programmer, and writing thousands of lines of code, I have learned so much about coding that these days I find myself not writing code at all, or very little code. ...
So after a while you start telling other people how to hit their nails, and before you know it, you are building entire tracts of homes.

But that isn't the end. Suddenly you find yourself hating the way everyone else hits those nails (just when someone starts to get good they leave) and the subsequent lack of quality* to which your name is attached. You come to realize that either you care about lots of houses with your name attached, or you care about the quality of each house with your name attached. It cannot be both.

Now you choose. Do it yourself and do it right; or just take all you can, while you can, and move on up the management ladder. What do you value?

* - see "Zen and the Art of Motorcycle Maintenance" by Pirsig

sdb

Re:QA

[Anonymous Coward]

If you encounter more than about 4 levels of indentation then the width of a tab is the least of your worries.

Objective-C

[bonch]

One of my favorite aspects of Objective-C is the way methods are self-documenting. "[Object doThis:something toThis:something]" is easy to figure out.

Uh,why does plain old text fail sometimes?

[Anonymous Coward]

// Begin Comment Header
// Comment Author:
// John Smith
// Programmer Analyst
// john.smith@company.com
// Comment Version:
// 0.0.1
// Comment Date:
// 2005.03.08
// End Comment Header
// Begin Comment
// increment i by 1
i++;

Bad documentation *is* better than none.

[Anonymous Coward]

Misleading docs can be worse than no docs at all, since someone without docs will have to dig through the code in front of them to understand it. Someone with bad docs will rely on the docs and wonder what's broken when things go awry.

If the code doesn't match the documentation, then you have found a bug! Either the documentation or the code is flawed: you need to revisit the actual requirements to determine which is the case. This may require revisiting the problem at it's source to determine the business, hardware, or safety requirements. When you find out the required behaviour, code it correctly, and then document it correctly!

If you blithely rely on either the code *OR* the documentation to be correct, you're being far too trusting...

Re:Code format

[kclittle]

This style
{
is better by far
{
because the braces 'belong' to
the following block of code
}
not the
{
preceeding guard statement
}
}

Sincerely,
An OFP (Old Fart Progammer)

Re:Code format

[Decaff]

All I gotta say is that if you use {
this {
style {
of indention
}
}
}

You are a newbie.

No way! I have been coding for 30 years...

It makes more sense to code

if (test) {
statement1
} else {
statement2
}

because the eye can immediately see from the 'if' and 'else' statements alone that a block of conditional code follows. Having the braces on the same line also marks out the lines as special: flow control code. I find that

if (test)
{
statement1
}
else
{
statement2
}

simply adds pointless extra lines to code, with no gain in readability.

Comments: they are documentation in the source

[wintermute42]

I've tried to work on projects where we developed new software as much as possible. However, taken all together I think I've probably spent many months of aggregate time reading other peoples code, modifying it, adding new features and fixing bugs. I hate doing this work, not only because of poorly designed software but because most software I've worked on is almost entirely undocumented (e.g., no comments and no external documentation).

Some posters have mentioned comments and documentation in this thread. But in my opinion, it has not been discussed in strong enough terms. For a long rant on this topic, see my essay Software and Documentation. I'll summarize some of the points I try to make in this essay here.

There were only a few people in this thread who wrote that they think that software source code is self documenting. This is a good sign. In the past this was a widely held view. Perhaps it is becoming less popular. Perhaps pigs are becoming airborne.

To those of you who wrote that your code is self documenting: you are simply lazy and unprofessional.

Sure I can understand what well written code does. But I cannot understand why it does what it does. I can show you three hundred lines of wavelet signal processing code. You can immediately understand what the code is doing. But you will have no clue what-so-ever about why it does what it does unless you understand the thinking behind the code. The same is true of any complex software.

Another problem is that even though I might understand what components do and perhaps even why they are doing what they do, getting an overall understanding of the architecture of a large application can be difficult and time consuming.

By not writing comments in your code and, for large applications, providing external documentation on the architecture, you are saving your time and effort, but forcing others to spend effort that you could have saved them.

Even if you have no consideration for anyone else who must maintain the application after you write it, comments will help you find bugs in your own code. Again and again I have found that when I explain my code in a comment I am forced to look over it again. In doing this I have found that the code does not do what I intended or that I left something out.

When it comes to documentation there is rarely enough. Even if you make an effort to document your code, when you are in the middle of it you will not document things that you find obvious. When you return later, these obvious issues will have been forgotten and are not obscure.

Documentation must be maintained along with the code. And it should be extended where it is incomplete or unclear. English (or what ever your language is): it's another kind of software.

Developers seem to fall into two camps: those who believe documentation is important and who do it and those who do not. I've managed software groups where I mentioned documentation in people's performace reviews and it still did not good. So far I have not been able to get someone who does not document to do it.

I have thought that perhaps one solution would be to hold code reviews where one of the major features that was looked at was understandability in the code. But I have not experimented enough to know if this will actually get people to document their software.

Literate programming not only involves writing well designed and well informed algorithms. It also includes writing documentation that explains these algorithms.

Obligatory quote

[jagne]

From Structure and Interpretation of Computer Programs by Abelson and Sussman:

"Programs should be written for people to read, and only incidentally for machines to execute."

Re:Comments need structure

[Anonymous Coward]

I find it useful to tell why I am doing something. A decent programmer can figure out what the code is doing, but even I have trouble 6 months later figuring out just why exactly it was that I did this, when this seems to be a better solution. Then I try the "better" solution, immediately realize why I went with the one I did. Saves me a lot of time in the long run to just document right there I did this b/c of that.

Re:Indentation

[AuMatar]

So you need guidelines to make a bad design decision work. This is what is generally called a "hack". The real solution is to not give semantic meaning to whitespace in the first place.

Consistency, good comments, and short code

[Grax]

Both consistency and good comments are good traits. I find understandable function and variable names are essential as well.

I believe that language familiarity has little to nothing to do with being a good programmer. A more familiar programmer can program faster but programming principles remain the same across all languages.

Smaller, simpler code is inherently less likely to contain bugs, runs faster, and is easier to troubleshoot.

If programmer A develops 1000 lines of code per day and programmer B develops 10 lines of code per day and both programs do the same thing I will pick programmer B every time (normal lines of code, not contest entries with runon lines and things)

Commenting in Eyecandy, ERP Modules & Space Cr

[Qbertino]

When I programm ERP Modules (in Python) I start with a large comment on what the module is supposed to do. I actually started doing this quite from the beginning. I write a litte summary of what the module does and comment heavily throughout the source. I even have debugging sessions were I only work on comments - often detailing them further.
I also do a lot of other programming (ActionScript rich media and stuff). I don't do opening or other comments there that much.
Why that?
If a multimedia app doesn't work I get an e-mail or a call asking to check into it within the next 24 hrs. The customer is anoyed or says that this comes bad with the end-user. We talk a little, I et to work and fix it within the next 10 hrs.
If a ERP module doesn't do what it's supposed to, I get a call on my mobile, with the CEO at the other end telling me that he's losing 200 Euro an hour because order processing has gone haywire.
This is a good point to end all discussion wether commenting is good or bad. When you are debugging a piece of code that keeps 3 people breathing you shure as well want it to be well commented.
The Lockheed Software Group, the people who write code for the space shuttle and other things, take this to the all-out extreme. They write EVERYTHING in a sort of human readable meta code, meta-comment THAT and then tranfer that to real code. They've had 3 bugs in 25 years - so I've heard. One of them being a counter problem that once would have nearly locked down a com-dish on an orbiter and prevented it from following it's target on earth after having rotated a certain amount. Figure: A millisecond of timing error in their code has the orbiter off course by 3 miles. I hear their comment line/code line ratio is about 7 to 1.

So much for "overcommenting is unprofessional".

Call everything by its right name

[blackhedd]

To think of code as literature is actually a non-obvious and striking idea.
The essence of literature is communication. I've been writing C and C++ for years, constantly fine-tuning and refining code and documentation, line by line, paragraph by paragraph. And how apropos to realize that the point is to express the thought so clearly and concisely that any reader (including yourself three weeks from now) will grasp it as close to immediately as possible.
That means you have to think clearly in order to code clearly. This matters more than almost anything else.
Too much documentation is just as bad as too little, since it obscures the intent of the code. How much is just enough? It takes years of thoughtful practice to know that.
Everyone is posting their favorite rules about coding standards. Most young programmers apply standards as rigid as they are incomplete. I have only two rules:
1) Call everything by its right name. Functions are verbs, variables are nouns. The name you give a object should express what it is or does, no more and no less, and be readable in English (or whatever your spoken language is). If you add something to a function that doesn't fit the function's name, it either belongs in a different function or else you misnamed the function in the first place. This takes constant review of your code, from a literary point of view.
2) Rules are made to be broken. All great writers unhesitatingly break the rules in order to communicate more clearly.

Languages are for communicating, and computer languages are no different. Keep that in mind at all times, and you'll become a wizard.

reading rule of thumb

[recharged95]

You'll notice good code is when you're reading the code and see comments at points when you question (yourself) the control flow from an architectural perspective. Then the developer's comments explain why he/she chose that path (i.e. the solution/algorithm/paradigm) and the pros&cons of his/her choice.

Hence, simple algorithms will likely have no comments in the implementation.

More of the time, comments that "supplement" the code usually add to the confusion for most advance developers.

comments are overrated

[menem]

Have you ever been in a code review that was a comment review? Where the reviewers, unwilling or unable to find problems in the code, nitpicked about how the comments looked like? Too many managers and second tier programmers spend their time worrying about the details of the comments and coding style because that is all they understand.

What good are great comments if the code doesn't work? Sure, comments matter, but all of the comments in the world aren't going to make buggy software run better. It will just make the next programmer understand how screwed up the original programmer was.