Microsoft Office for OS X has around 30 million lines of code. Damn.
Archive for the ‘Software’ Category
I’ve recently had the opportunity to work with a large, unfamiliar code-base. The experience has made me reflect on some of my own coding practices and on writing more maintainable code. Much has been written on this topic, but here are the things that I feel are most important and have a high payoff without much (if any) additional work.
Make use of inherent metadata
Programming languages have inherent metadata in how you name things, what types you use, scoping, visibility, etc. This information is invaluable for someone new looking at the code and helps make the code self-documenting. There are several things you can do here:
Use good names
- Give classes, variables, methods, functions, etc. descriptive, differentiable names. Things that are related should have similar names, while things that are not should not.
- Keep the names up-to-date. If functionality changes, update the name.
- Variables with different scopes should be differentiated. For example, prefix instance variables with an underscore.
- Be consistent.
- Don’t create variables for things you only use once – just put them inline. Then I don’t have to figure out where else the variable is used.
Use appropriate types
- If possible, don’t use multi-level typedefs. It’s a real pain in the ass to go through 5 header files to figure out that foo_bar is an unsigned integer. And don’t typedef pointers away – I want to know if something is a pointer or not. Especially don’t typedef pointers away by inventing your own syntax (e.g. CFArrayRef is a CFArray pointer). The language already has syntax for that.
- Do use typedefs for things like enums.
- Use the most-specific type possible. If something should not be negative, make it unsigned, etc.
Use appropriate visibility
If something should only be used within a class, make it private. People looking at the code then don’t need to worry about external clients.
Keep things short
Nothing is more depressing than trying to grok a long method/function/class. There shouldn’t be hard rules on length, but I try to write methods/functions that fit on one screen, and to keep my classes under around 1000 lines of code. Without caution, this can lead to a method/class explosion, but I’d rather grok a small class cluster than one gigantic class.
Keep block nesting to a minimum
Don’t have a while loop inside an if, inside an else, inside a for loop, inside an else if, inside an do/while loop, inside a …
If I have to understand more than a small portion of the code to change one class, there is a problem.
Write useful documentation
You don’t need a lot. Here is what I think is important:
- Describe briefly what a method/function does. No method or function should be so complicated that this is more than a sentence or two.
- If a method is overriding a superclass, note that and explain why.
- Explain anything unusual or complicated.
- If a method has concurrency issues (should only run on the main thread, etc), note those.
Think of those that come after you
Whenever you write some code, try to put yourself in the shoes of the next programmer to work on the code. This is the programmer’s version of the seven generations rule.
There is a huge discussion over at Coding Horror about Wasabi, the in-house extension of VBScript used by Fog Creek Software for FogBugz. The general consensus seems to be that Joel has lost his mind. However, if you read what Joel originally wrote, as well as his responses in the thread, the Wasabi solution is not unreasonable.
Fog Creek had a large codebase of existing VBScript, which they did not want to throw away. However, they do want to deploy it to Unix and their customers want minimal installation dependencies (i.e. it should work out of the box). Their solution was to develop an extension to VBScript called Wasabi, which then compiles down to pure VBScript or PHP. This accomplishes their goals rather elegantly.
So why do people think this is crazy?
Argument One: Writing Your Own Language is Dumb
In general, writing your own language is overkill. However, it may be appropriate, particularly in the domain-specific language case. According to Joel, Wasabi took one person two months to write. Their existing application code was then cross-platform without any modification, and will remain so going forward. They can also add domain-specific or just handy features to the language and have them work on all target platforms.
Argument Two: No one outside of Fog Creek knows Wasabi
So what? It’s a superset of VBScript. Good programmers can pick up new languages quickly.
Argument Three: Joel’s Statements are Internally Inconsistent or Incorrect
Some of these are true, but not the ones about Wasabi. His arguments about Ruby may or may not be valid, but that has no bearing on whether Wasabi was a good idea or not. Further, the advice/recommendations he gave his friend in the original article were about creating a new web application, not dealing with a six year old code-base. The problems are very different.
I don’t always agree with Joel, but all this furor over Wasabi is ridiculous.
Philip Greenspun writes about What’s wrong with the standard undergraduate computer science curriculum. He makes good points, based on my experience in such a curriculum.
The new graduate has had four years of experience in tackling well-defined clearly specified problems that have been broken down into small tasks.
Yes. Assignments requiring any real thought or design were rare. I feel fortunate that I pursued my own projects – I know for certain that they were instrumental in my being hired into my current job. What always startled me was that my peers were satisfied limiting themselves to their schoolwork. I would expect more passion about the field to which you are devoting years of your life.
Graduates haven’t done much group work. Universities spend $billions on facilities so that students can sleep together; $0 on facilities so that students can work together.
We did a fair amount of group work, but in general it was group work for the sake of group work. It was rare for an assignment to actually require true group work. The exceptions were some of my better college experiences.
Lack of experience with user interface design and testing and no experience handling real users’ suggestions, complaints.
It is very easy to go through college without doing any user interface programming. I had only one course where it was required, and that was a graduate-level technical elective. Even there, the interface was of very secondary concern.
Our students should be able to study 48 weeks per year, …, and finish their bachelor’s degree in 30-36 calendar months
I would hate this personally. Graduates today will be working for 40 or 50 years – why compress youth even further? One of the best parts of college was that it did not take up all of my time.
I think a reasonable addition to the curriculum would be to replace some courses with extensive projects, one for each year. Together, the projects would provide a number of different experiences.
In year one, the student would choose a relatively simple project with the assistance of an advisor. It should be sufficiently complicated as to take the full two semesters to complete, but not so complex as to be overwhelming.
In year two, the student would take someone else’s project from year one and make a version 2.0. Ideally, the project should be in a different domain from their own original project. This would give the student experience in maintenance programming and dealing with other people’s code.
Years three and four would repeat this pattern, except that the students would work in small teams. The projects would be sufficiently complex that if students did not divide work efficiently, they would fail.
As best as possible, the combination of the four projects should cover a wide area of domains. User interface, networking, databases, security, testing, software design, maintenance, algorithms, data structures, and others could all easily be incorporated. Other skills are naturally developed in this model. Years three and four would require teamwork, while writing about and presenting their projects would develop communication skills.
Finally, all students would leave college having completed four sizable projects in different domains and likely different programming languages. Students should retain ownership of their projects, in case any have market potential.