“…is getting your code to communicate”

After opening with a tragic and beautiful description of the lifecycle of the sun, Uncle Bob dives into some nitty gritty advice in the fifth episode of Clean Coders: Form. Most of the episode focuses on specifics of what can help make your code look like well written prose—and thus, read like it. He also expands on a topic I struggled with in the last episode, and nestled in there he drops one his usual are you kidding?!?! statements that I’ve come to expect— the kind where a rookie like me thinks he’s crazy— and then I realize just how right he is.

The Devil is in the Details: Comments, Spaces & Blank Lines

I won’t go over all of his specific syntactical recommendations, but the core of his argument is: “When someone first looks at our code we want them to be impressed by the attention to details…convinced that professionals were at work.”

This statement rings loud and clear with that English degree someone gave me way back when. If we want our code to read like well-written prose it should follow generally accepted standards. There was also just an interesting article in the Harvard Business Review by Kyle Wiens, the co-founder of iFixit, who applies a grammar test to all of his job applicants.

Comments: Don’t do it

Uncle Bob’s take on comments: “Every Time you write a comment, you fail”. His argument is that code should be expressive enough (with well-named variables and methods) that it speaks for itself. Although he admits that there are times that comments are absolutely necessary, he “doesn’t congratulate himself” when he has to write one. The other thing that people forget about comments is that they never stay relevant. Chances are likely that there will be something in the near future that will change the code the comment refers to.

The Two Partition Sandwich: “App” and “Main” with a Slice of Abstraction

In episode four Uncle Bob introduced the concept that you should be able to draw a line between where the application and the lower level modules are. Examples of the lower level modules would be database and views. Both should essentially be “plug-ins” to the rest of your application, and dependencies should flow away from the lower-level modules so that your app doesn’t depend on the implementation of the database or view. The higher level and lower level modules should both flow towards an abstraction layer that allows you change out the lower level modules if necessary.

“Getting your code to communicate is even more important than getting your code to work”

This was the statement that made me hit pause on the video and ask “Huh? Is he serious?”. I mean, having code that gets the job done is the most important thing, right?

…and then a moment passed and I thought, “well, what if I can’t even get my code to work? I just need to get it to work, right?” And of course I do need to get it to work, but what do we usually do when we can’t figure something out? We ask somebody else for help. That means Uncle Bob is right on at least one count— because if our code doesn’t work but is at least well-written then the people helping us have a better chance of understanding what we’re doing.

…and then a couple of more moments passed, and I realized that “getting the job done” means a lot of different things. If you just want to get the code to work with no regard to the future or change— new features, different lower-level details, optimizations— then that’s a job you can do, but over a very brief course of time it won’t be a job that you’ll be proud of. The next person to come along and work on your code is not going to be “impressed by the attention to details…convinced that professionals were at work.” And to quote Stephen Degutis from last week’s 8th Light U, “you in six months is another person”. No, getting the job done should mean writing clean, decoupled code that communicates to a reader exactly what’s going on. If something needs to be changed or built upon it then there should be a solid foundation to start from.