5 Best Practices for Commenting Your Code

One of the first things you learn to do incorrectly as a programmer is commenting your code. My experience with student and recently graduated programmers tells me that college is a really good place to learn really bad code commenting techniques. This is just one of those areas where in-theory and in-practice don’t align well.

There are two factors working against you learning good commenting technique in college.

  1.  Unlike the real world, you do a lot of small one-off projects as a solo developer.  There’s no one out there fantasizing about dropping a boulder on you for making them decipher your coding atrocity.
  2.  That commenting style you are emulating from your textbook is only a good practice when the comments are intended for a student learning to program. It is downright annoying to professional programmers.

These tips are primarily intended for upstart programmers who are transitioning into the real world of programming, and hopefully will prevent a few from looking quite so n00bish during their first code review. Code Review? Oh yeah, that’s something else they didn’t teach you in school, but that’s a whole other article, I’ll defer to Jason Cohen on that one.

So let’s get started…

(1) Comments are not subtitles

It’s easy to project your own worldview that code is a foreign language understood only by computers, and that you are doing the reader a service by explaining what each line does in some form of human language. Or perhaps you are doing it for the benefit of that non-programmer manager who will certainly want to read your code (Spoiler: He won’t).

Look, in the not too distant future, you will be able to read code almost as easily as your native language, and everyone else who will even glance at it almost certainly already can. By then you will realize how silly it is to write comments like these:

// Loop through all bananas in the bunch
foreach(banana b in bunch) {
    monkey.eat(b);  //make the monkey eat one banana
}

You may have been taught to program by first writing  pseudo-code comments then writing the real code into that wire-frame. This is a perfectly reasonable approach for a novice programmer. Just be sure to replace the comments with the code, and don’t leave them in there.

Computer: Enemy is matching velocity.
Gwen DeMarco: The enemy is matching velocity!
Sir Alexander Dane: We heard it the first time!
Gwen DeMarco: Gosh, I’m doing it. I’m repeating the darn computer!

-Galaxy Quest

Exceptions:

  • Code examples used to teach a concept or new programming language.
  • Programming languages that aren’t remotely human readable (Assembly, Perl)

(2) Comments are not an art project

This is a bad habit propagated by code samples in programing books and open source copyright notices that are desperate to make you pay attention to them.

/*
   _     _      _     _      _     _      _     _      _     _      _     _
  (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)    (c).-.(c)
   / ._. \      / ._. \      / ._. \      / ._. \      / ._. \      / ._. \
 __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__  __\( Y )/__
(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)(_.-/'-'\-._)
   || M ||      || O ||      || N ||      || K ||      || E ||      || Y ||
 _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._  _.' `-' '._
(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)(.-./`-'\.-.)
 `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'  `-'     `-'

                 -It's Monkey Business Time! (Version 1.5)
*/

Why, that’s silly. You’d never do something so silly in your comments.

ORLY? Does this look familiar?

   +------------------------------------------------------------+
   | Module Name: classMonkey                                   |
   | Module Purpose: emulate a monkey                           |
   | Inputs: Bananas                                              |
   | Outputs: Grunts                                            |
   | Throws: Poop                                               |
   +------------------------------------------------------------+

Programmers love to go “touch up” their code to make it look good when their brain hurts and they want something easy to do for a while. It may be a waste of time, but at least they are wasting it during periods where they wouldn’t be productive anyway.

The trouble is that it creates a time-wasting maintenance tax imposed on anyone working with the code in the future just to keep the pretty little box intact when the text ruins the symmetry of it. Even programmers who hate these header blocks tend to take the time to maintain them because they like consistency and every other method in the project has one.

How much is it bugging you that the right border on that block is misaligned? Yeah. That’s the point.

(3) Header Blocks: Nuisance or Menace?

This one is going to be controversial, but I’m holding my ground. I don’t like blocks of header comments at the top of every file, method or class.

Not in a boat, not with a goat.
Why? Well let me tell you, George McFly…

They are enablers for badly named objects/methods – Of course, header blocks aren’t the cause for badly named identifiers, but they are an easy excuse to not  put in the work to come up with meaningful names, an often deceptively difficult task. It provides too much slack to just assume the consumer can just read the “inline documentation” to solve the mystery of what the DoTheMonkeyThing method is all about.

JohnFx’s Commandment:
The consumer of thy code should never have to see its source code to use it, not even the comments.

They never get updated: We all know that methods are supposed to remain short and sweet, but real life gets in the way and before you know it you have a 4K line class and the header block is scrolled off of the screen in the IDE 83% of the time. Out of sight, out of mind, never updated.

The bad news is that they are usually out of date. The good news is that people rarely read them so the opportunity for confusion is mitigated somewhat. Either way, why waste your time on something that is more likely to hurt than help?

JohnFx’s Maxim of Plagiarized Ideas :
Bad Documentation is worse than no documentation.

Exception: Some languages (Java/C#) have tools that can digest specially formatted header block comments into documentation or Intellisense/Autocomplete hints. Still, remember rule (2) and stick to the minimum required by the tool and draw the line at creating any form of ASCII art.

(4) Comments are not source control

This issue is so common that I have to assume that programmers (a) don’t know how to use source control; or  (b) don’t trust it.

Archetype 1: “The Historian”

     // method name: pityTheFoo (included for the sake of redundancy)
     // created: Feb 18, 2009 11:33PM
     // Author: Bob
     // Revisions: Sue (2/19/2009) - Lengthened monkey's arms
     //            Bob (2/20/2009) - Solved drooling issue

     void pityTheFoo() {
          ...
     }

The programmers involved in the evolution of this method probably checked this code into a source control system designed to track the change history of every file, but decided to clutter up the code anyway. These same programmers more than likely always leave the Check-In Comments box empty on their commits.

I think I hate this type of comment worst of all, because it imposes a duty on other programmers to keep up the tradition of duplicating effort and wasting time maintaining this chaff. I almost always delete this mess from any code I touch without an ounce of guilt. I encourage you to do the same.

Archetype 2: “The Code Hoarder”


     void monkeyShines() {
          if (monkeysOnBed(Jumping).count > max) {
             monkeysOnBed.breakHead();

             // code removed, smoothie shop closed.
             // leaving it in case a new one opens.
             // monkeysOnBed.Drink(BananaSmoothie);
          }
     }

Another feature of any tool that has any right to call itself a SCM is the ability to recover old versions of code, including the parts you removed. If you want to be triple super extra sure, create a branch to help you with your trust issues.

(5) Comments are a code smell

Comments are little signposts in your code explaining it to future archaeologists that desperately need to understand how 21st century man sorted lists of purchase orders.

Unfortunately, as Donald Norman explained so brilliantly in The Design of Everyday Things, things generally need signs because their affordances have failed. In plain English, when you add a comment you are admitting that you have written code that doesn’t communicate its purpose well.

Sign:”This is a mop sink.” Why would that be necces… oh.

Despite what your prof told you in college, a high comment to code ratio is not a good thing.  I’m not saying to avoid them completely, but if you have a 1-1 or even a 5-1 ratio of LOC to comments, you are probably overdoing it. The need for excessive comments is a good indicator that your code needs refactoring.

Whenever you think, “This code needs a comment” follow that thought with, “How could I modify the code so its purpose is obvious?”
Talk with your code, not your comments.

Technique 1: Use meaningful identifiers and constants (even if they are single use)

     // Before
     // Calculate monkey's arm length
     // using its height and the magic monkey arm ratio
     double length = h * 1.845; //magic numbers are EVIL!

    // After - No comment required
    double armLength = height * MONKEY_ARM_HEIGHT_RATIO;

Technique 2: Use strongly typed input and output parameters

      // Before
      // input parameter monkeysToFeed:
      // DataSet with one table containing two columns
      //     MonkeyID (int) the monkey to feed
      //     MonkeyDiet (string) that monkey's diet
      void feedMonkeys(DataSet monkeysToFeed) {
      }

     //  After: No comment required
     void feedMonkeys(Monkeys monkeysToFeed) {
     }

Technique 3: Extract commented blocks into another method

      // Before

      // Begin: flip the "hairy" bit on monkeys
      foreach(monkey m in theseMonkeys) {
          // 5-6 steps to flip bit.
      }
      // End: flip the "hairy" bit on monkeys

     // After No comment required
     flipHairyBit(theseMonkeys);

As an added bonus, technique 3 will tend to reduce the size of your methods and minimizing the nesting depth (see also “Flattening Arrow Code”) all of which contribute to eliminating the need for commenting the closing tags of blocks like this:

            } // ... if see evil
         } // ... while monkey do.
      } // ... if monkey see.
    } // ... class monkey
  } // ... namespace primate

Acknowledgments

Several of the ideas presented here, and a good deal of the fundamental things I know about programming as part of a team, I learned from the book Code Complete by Steve McConnell. If you are a working programmer and have not read this book yet, stop what you are doing and read it before you write another line of code.

Advertisements

Shortcuts for registering COM objects or NET assemblies

TipsHere are a few shortcuts to simplify working with assemblies (either COM or .NET) that I have found especially useful over my years as a developer.

 

 

 

 

 

Tip 1: Associate DLL and OCX file extensions with RegSvr32

If you are still working with COM style objects regularly, associating the DLL and/or OCX extensions with RegSvr32.exe (in the Windows\system32 directory) allows you to register or re-register them quickly by double-clicking the file in explorer.

Associate RegSvr32 with DLL Extension - Step 1

Step 1: Right-Click a DLL file and choose the "Open With..." command.

 

BrowseFileExtRegSvr32

Step 2: Browse to WindowsWin32Regsvr32.exe

 

For those of you who work with managed assemblies more often, but still do a lot of interop work, an alternative is to associate DLL files to Regasm.exe or Regsvcs.exe

 

Tip 2: Use Windows “Send To..” folder for quick access to unregister a DLL

So now you can register components easily, what about un-registering them? That’s a snap too.

Just create a shortcut in the C:\Documents and Settings\{profilename}\SendTo directory with the target attribute set to %windir%\system32\REGSVR32.EXE /u and name the shortcut “Unregister DLL”

Shortcut to Unregister a DLL

Here it is in action

 

The He-Man Muggle Haters Club for Programmers (part 2)

This is the second article in a two-part series. If you haven’t already, please read Part One first.

 


 Protecting Our Interests

Although we may be loathe to admit it, we want and need programming to be sufficiently complex to keep the unwashed masses out of our clubhouse. The trouble is, we need a barrier to entry to support our value as programmers. Unlike lawyers and doctors who have expensive degrees and trade associations to protect their earning potential and aura of authority, it is not uncommon for a programmer to make a good living without the benefit of academic credentials or a formal endorsement of an organization. It is the magic of our craft that makes us feel special and separates us from the muggles and wanna-be’s like your boss’s nephew who is really good with computers.

 

Shhh! Muggles Are Everywhere

Fundamentally, I think this is a quite valid concern and admit that I sometimes succumb to these same territorial instincts. Especially when provoked by ignorant statements that undermine the investment programmers continually make in a Red Queen’s Race to stay on top of their game.

 

 

 

 

The Salman Rushdie of Programming?

Be Honest. How many of you have the urge to burn  this guy as a heretic?

There’s no reason why office workers, homemakers, professional engineers and pizza delivery persons shouldn’t be able to take advantage of their own hand crafted custom computer programs to work faster and smarter. It shouldn’t take a ‘professional programmer’ (whatever that is) to do the job. You know what needs to be done better than anyone else. You can do it yourself! (And I say this as someone who has spent many years writing programs for other people … ‘professionally’.)
VB Programming for the non-programmer!

Before everyone starts jumping on the VB dogpile in the comments, I should clarify that the referenced article is actually about VBA, and not VB proper. I’m sure, however, that many of my readers will question whether that distinction is meaningful inspiring yet another battle in the platform wars. This brings me back to my point.

 Why do many programmers despise tools like Access and VB, and even those that use VB look down on those who do too much drag-drop programming. The concept of a non-technical person using tools like this to build a useful software drives some of us nucking futs. Why? Shouldn’t we welcome usability to simplify the task of software construction?

Perhaps because it opens that clubhouse door a bit too wide for comfort.

 

"Sir, you can't let him in here. He'll see everything. He'll see the big board!"- General "Buck" Turgenson

Sir, you can’t let him in here. He’ll see everything. He’ll see the big board!

– General “Buck” Turgenson

 

 

 

 

Gold Plating The Secret Handshake

It is my contention that this effect has played a role in driving recent trends in programming technology. After years of considerable progress towards simplifying the physical act of programming (ASP.NET), recent developments in technology built for programmers has decidedly shifted towards better implementation of computer science-y stuff like functional programming, MVC and lambda expressions into the more pedestrian programming languages.

Also, the attention of developers is increasingly turning to the haute couture*technology of the day. Ruby? That is so two years ago, don’t you know we are using Scala now? (Haskell)

* The use of haute couture in this blog is not sanctioned by the French Government. For my French or Bostononian readers, please substitute the phrase “Wicked Awesome.”

This seems to drive programmers, who like woodworkers often build their own tools/jigs, to devote our time to constantly moving goalposts rather than reducing the required expertise to build functional software.

 

The Consequence and My Conclusions

I’m not saying that new programming languages don’t add value, just that this type of progress is more about fine tuning than making programmers generally more productive. My inner pragmatist makes me question the need to sharpen our tools to such a degree when the majority of the programming work seems to be centered on developing CRUD apps.  Additionally, given the very real threat of “low-cost” outsourcing options for programmers, it also makes me wonder if perhaps our priorities are not aligned with our best interests.

 

Don’t Go Away Angry

I fully realize that I have engaged in some very controversial conjecture in this series, and want to emphasize that the intent of this article is is not to drive a particular agenda. Rather, I’m merely trying to encourage introspection into some aspects of our trade that may have otherwise gone under-examined. I am not certain that I even agree with all of the opinions I have offered here, but found musing on them interesting and hope you will too.

The He-Man Muggle Haters Club for Programmers (part 1)

Little Rascals - He-Man Woman Haters Club

In his satirical and quite humorous article, “How to Write Unmaintainable Code,” Roedy Green raises an interesting question that really got me thinking about some things I had previously taken for granted with the the physical act of creating software.

 

 

 

“Why is programming still done primarily in a text editor?” 

 Before get rolling with my analysis of this question, please take a moment to read his conjecture on the topic. I’ll meet up with you again at the the other end.

Imagine having an accountant as a client who insisted on maintaining his general ledgers using a word processor. You would do you best to persuade him that his data should be structured. He needs validation with cross field checks. You would persuade him he could do so much more with that data when stored in a database, including controlled simultaneous update.

[Now] imagine taking on a software developer as a client. He insists on maintaining all his data with a text editor. He is not yet even exploiting the word processor’s colour, type size or fonts.

Think of what might happen if we started storing source code as structured data. We could view the same source code in many alternate ways, e.g.  as a decision table, a flow chart, a loop structure skeleton,  Java with various levels of detail or comments removed, as Java with highlights on the variables and method invocations of current interest, or as Java with generated comments about argument names and/or types.  You could see code with additional or fewer parentheses, (depending on how comfortable you feel with the precedence rules).

You could use the full colour abilities of the modern screen to give subliminal clues, e.g. by automatically assigning a portion of the spectrum to each package/class using a pastel shades as the backgrounds to any references to methods or variables of that class. You could bold face the definition of any identifier to make it stand out.

You could ask what methods/constructors will produce an object of type X? What methods will accept an object of type X as a parameter? What variables are accessible in this point in the code? By clicking on a method invocation or variable reference, you could see its definition, helping sort out which version of a given method will actually be invoked.You could do quite a bit of code writing by point and click.

He has some interesting points, doesn’t he? The comparison to an accountant using a word processor to create journal entries really struck me. I began to think about the Sisyphean labors of applying language/compiler specific markup in our code to satisfy our brutal task-master. It is easy to start thinking about programming IDE’s and compilers as a special class of software that is exempt from the normal  usability considerations because it is geared towards computer experts, but that just isn’t true.

Put Themselves in our Shoes

Consider the reaction of your users if you required them to enter data in your application using a big text-box using well-formed XML to provide context and meaning to each individual item. Sure they’d complain because they can’t remember the relevant attributes and always forget to close their tags, but that would be easily solved by updating the text box to have Intellisense!

Actually, no it wouldn’t. Clearly the intellisense solution addresses only the symptom, not the problem.

We Deserve Better

So why is it good enough for us?  Don’t programmers deserve good usability in our tools too?  Is it really necessary to spend valuable time matching up brackets/parens and chasing down missing line terminators?  Worse yet, if you frequently use different languages, the mental context switches force you into all sorts of mental gymnastics to keep it straight,  and incite a scolding from your compiler.

Why do we have to keep syntax ideosynchracies in our heads?

var myInteger //This is a Javascript comment
Dim myInteger as Int 'This is a VB comment
int myInteger  //This is a Java or C++ comment
myInteger=5 # This is a Ruby Comment
DECLARE @myInteger int --This is a t-SQL comment

Creating good visualizations for scoping, variable declaration and module interfaces is not an unsolvable problem. Also, the benefits of one more level of abstraction extend beyond increased productivity. For example, consider the portability that the increased normalization of code could produce.

Or Maybe Not…

At this point I am sure that many of you are still skeptical, and I am about to slam the door on the open mind of the remainder of you. What I am describing here is effectively form-based (a.k.a “drag and drop”) programming.

That Whooshing is the sound of this article entering free-fall from angry programmers down-voting it on Reddit.

This is exactly why we are still programming in glorified text-editors, because that is exactly what we want. And unlike programmers who write software for marketing people, the developers who create programming languages and IDE’s understand very well that other programmers emphatically prefer some additional complexity to even the remote possibility of democratizing software development.

Homework Assignment

As a mental exercise and preview of the finale of this article, consider this diagram showing the general sense of  superiority among programmers in the style of the famous Geek Hierarchy poster and ask yourself which direction the arrow would go in terms of general usability of the tools for each type of programmer.

Hierarchy of the World According To Programmers

Hierarchy of the World According To Programmers

 

To be Continued…

In part two of this series I discuss the psychological and frankly pragmatic reasons that our techno-brethren are so committed to keeping the field of programming as exclusive and specialized as possible.

Poll: What factor is most likely to or has driven you out of a career as a programmer?

In my previous article,  “Programmers: Before you turn 40, get a plan B”  several of my readers pointed out the staleness of the NYT article that I cited along with its citation of a joint NSF/Census Bureau study*  indicating a high dropout rate for software developers.  Further, the original study utilized some questionable sampling methods by  focusing on programmers with a CS degree, which is not a prerequisite for a programming career.

* [Citation Needed] If anyone can find a copy of this study on-line, please send me a link.

Although I don’t claim to be a journalist, it doesn’t excuse my sloppy journalism. As an act of penance, I am going to attempt to collect some fresh data to test whether this theory still holds and investigate the causes of attrition in our business by polling my readers. Please help me maintain at least a modicum of scientific rigor and only respond on the polls that are relevant to your specific situation.

I’ll post the results and discuss them in an upcoming article, but the impatient among you can see the results by clicking on the link at the bottom of the poll.

 

 

BTW: Sorry the Polls are formatted so wonky. I’ve gotto find a better poll widget provider than PollDaddy.

Usability Rant: When bad design decisions become standards

John is in a crotchety phase today
Crotchety Mood
@1914 Andy Rooney

Prior to starting this blog a few months ago, I rarely had occasion to write much more than a few paragraphs in a browser based editor. In this short time, I am starting to understand why most serious bloggers seem to write their posts offline in traditional word processing software. Despite the best efforts of web developers, the browser platform is a usability nightmare fraught with peril for innocent users and their precious data.

Forgive my Andy Rooney impression, but what has me in a crotchety mood is the behavior of the backspace key in modern browsers. I understand how convenient it seems that browsers have a function to navigate backwards and there is a handy over-sized key with the word “Back” printed right on it, but sorry that key had a meaning that predated personal computers and far-predated browsers.

My Mental Map says, “Backspace = delete the last typed character.”

“But,” my tormentors would say, “you can still use backspace that way when you are in a text field. We’ve just overloaded it so that you can also use it to navigate to the previous page.”

angryuserThat is true, but it is very common for a browser to rip focus away from the edit control unexpectedly, invisibly, and unapologetic ally. –I’ll save that rant for another day– If you hit the backspace key after the focus drifts away…BAM…you wind up on on another web page and will never get back that insightful three page retort to that ignoramus who thinks Piccard was better than Kirk and the world of literature will be diminished for its loss.

Giving the user the ability to irrevocably wipe out a big chunk of their work with a single key press violates a number of the fundamental principles of usability engineering, most importantly:

User input is sacred, protect it at all costs!

Your problem is right here, m’aam.

The core problem here is the inappropriate use of modes. Application modes turn friendly UI elements and device controls into two faced bastards that promise one thing and do another and then pin the blame on you because you didn’t catch the context switch. Modes are especially evil in situations like my example of the backspace key because they turn a  harmless action (delete one character) into a catastrophic one (exit without saving).  It is like having a button on a soda machine explode instead of dispensing a Dr. Pepper because it is Sunday and that is just how they roll in Waco.

I”m not saying that modes have to be avoided at all costs, just that you should recognize that they incur a debit against usability and they should be demoted to a fallback option where there are simply more functions necessary than controls available to map them to. But don’t take my word for it.  Don Norman also recognized the danger of relying on context based function mapping in his awesome exploration of the interaction between humans and machines…

“Mode errors are inevitable any time equipment is designed to have more possible actions than it has controls or displays, so the controls must do double duty. [They] are especially likely when the equipment does not make the mode visible…”
The Design of Everyday Things – Donald A. Norman

Mitigation Strategies

If you find that a modal approach is the only option, at least implement it responsibly.  Follow these best practices when implementing a modal interface to minimize the potential for leading your users into annoying mode errors:

  1. Make it obvious to the user which mode they are in at all times. For example by changing the label on controls.
  2. Mode changes should be initiated as an intentional act by the user, not the software or as a side effect of an unrelated action.
  3. If #2 isn’t possible, at least make the mode switch obvious, but unobtrusive. That is, don’t ask them to confirm it.
  4. Recognize that mode errors will happen despite your best efforts. Anticipate them and make it easy to fix their consequences.
  5. Don’t use a mode as an excuse to force the user to memorize arbitrary and illogical control mappings.

The Legacy of The Browser Backspace Atrocity

Evil Backspace

Unnecessary Modes Are Evil

As best I can tell, though I haven’t yet confirmed it. This behavior originated in Internet explorer and has since spread to all of the popular browsers. I have confirmed the mapping of the backspace key to the back-navigation function on Windows in IE7, FireFox 3, and Google Chrome.  I suppose it is a standard now at least for Windows. Peachy.

Meanwhile, there is a growing cadre of browser users who LIKE this “feature”, are requesting it be added to other browsers, or even trying to hack it back into browsers that haven’t implemented it.

That said, a quick Google search indicates that a considerable number of developers are also trying to hack it OUT of the browser for their sites. Ultimately, the behavior has existed long enough that it will be politically impossible to undo and will force web developers who know something about UI design to continue to work around it for the sake of their users.

What Programmers Should Be Learning in College

 graduate_computer

I officially graduated last weekend ending an undergraduate effort that started at the University of Texas at Austin 20 years ago in 1989 and stalled in a hiatus that turned into a full-time career. 

With the help of my employer’s generous tuition reimbursement plan and the flexibility of the distance learning program at the UMass I finally managed to not only wrap things up and earn a BS in Information Systems, but in doing so earned the Chancellor’s Medal for Academic Achievement. Who knew I had it in me to graduate at the top of my class for my college?

 

The experience of going back to school so many years later has been eye opening and has provided a lot of context to my recruiting efforts for greenhorn programmers. That is, I’ve walked a mile in their shoes and seen what is currently being taught in college level Information Technology programs.

 

The Good News

Contrary to my expectations forged from my previous collegiate experience, the problem of professors teaching outdated technology and theory has been remedied to a considerable degree, at least in the UMASS program. Many of the classes were taught by adjunct professors that worked at least part time in the real world in addition to their academic duties.  This made the lessons much more relevant and practical. Also, I’m glad to see they have moved on from Turbo Pascal and 68000 Assembly, but then I am dating myself.

 

The Bad News

The curriculum is still very centered on learning specific technologies and was conspicuously weak on best practices or practical preparation for aspects of software engineering outside the scope of software construction.  Given the relatively small percentage of time that a working programmer spends on writing code versus other elements of the software construction process, this is not ideal.

 As a hiring manager, I’d greatly prefer graduates with a good grasp of basic software construction and project management skills than proficiency in a specific programming languages. Software platforms exhibit such a short half-life that I’d question the long term value of them anyway aside from the foundational ones like C++.

Concepts such as those described in the canons of programming literature like Code Complete  and The Mythical Man-Month, can provide more lasting value over the life of a programmer’s career.

 

Proposed Curriculum for Software Engineers

The following course of study is a recommendation based on the skills that I’d like to see when I interview entry level software developers. I am not saying that existing programs don’t include some or all of these elements, but I rarely see many of these skills when interviewing recent college graduates.  I’ve broken the topics out for clarity, but clearly some should be combined or split into multiple courses.

Freshman Year – The fundamentals

  • Overview of Operating Systems:  Working knowledge and exposure to at least 3 of the most commonly used operating systems, i.e.  Windows, Linux, OSX, etc. The ulterior motive is to derail platform bigotry before the mental cement dries.
  • Overview of Programming Languages:  Exposure to a variety of languages by writing very basic programs in each. (C#, C++, Ruby, VB.NET, Perl).
  • Scripting 101: Familiarity with the most basic programming concepts such as variables, methods, control structures, etc. without the overhead of more advanced programming concepts to provide a comfortable “wade-in” point for those new to programming.
  • Application Architecture: Become familiar with common application architectures, associated issues, and relevant technologies. (Desktop, Client-Server, N-Tier, Web, Embedded, AJAX, etc.)
  • Intro to Electrical Engineering: Hardware level programming as an analog for software development. Boolean algebra, basic circuit design, logic gates, etc.
  • Database Design Principles and Theory: Set Theory, Normalization, OLAP, ROLAP, etc.
  • Networking Basics: Topics including, networking hardware, topologies, the OSI model, basic signaling, and protocols.

 Sophomore Year – Filling the toolbox

  • Reporting Tools and BI: Crystal, Cognos, SQL Server Integration Services
  • Database Query Languages: Query language and  technique in ANSI-SQLsome coverage of PL/SQL and t-SQL.
  • Programming in <Student’s Choice>: In depth programming course in the language of the student’s choice.
  • Source Code Control Tools and Best Practices
  • Technical Writing: Best practices for creating of software documentation and help systems that are useful to real people.
  • The Build Process and Change Management

 Junior Year – Sharpening the tools

  • Programming for a Diverse world: I18N, L10N, Unicode, etc.
  • Writing Secure Code: Common application security vulnerabilities and how to avoid them (SQL Injection, XSS, Buffer Overflows, etc.)  Suggested Text – “Writing Secure Code
  • Programming Technique: OOP, Design Patterns, Refactoring, Coupling Cohesion.
  • Usability / User Experience: Suggested text – “About Face 2.0: The Essentials of Interaction Design

 Senior Year – From machinist to craftsman

  • Designing Software: Requirements Gathering, Use Cases, Prototyping.
  • Software Project Management and Estimation: Agile, Waterfall, etc.
  • Team Programming: Code review, pair programming.
  • Testing Software: Tools and technique (Unit, Automated, Load, Regression, Integration)
  • Profiling and optimizing code: Static/Dynamic code analysis, Big-O Notation.
  • Debugging/Troubleshooting:I am amazed at how impressively bad a lot of working programmers are at this. Suggested Textbook: “Debugging: The 9 Indispensable Rules for Finding Even the Most Elusive Software and Hardware Problems.”
  • Problem Solving in Code: Problem solving and more in-depth exposure to the programming language of the student’s choice.