This article on discussing coding style guide considerations for companies that actually want to save money on development costs by making life more easy for their developers to maintain their code moving forward. I started this article as a sidebar rant on verbose code that I’d included in a beginner’s tutorial. I was imploring future developers to buck the trend of opting for code brevity over code readability. Which is a habit that saves pence on storage, nothing in execution time these days (I’ll explain later) and as an ‘at-the-coal-face’ developer and a manager of developers, I’ve seen first hand how many wasted hours that could have been easily avoided by the addition of a comment or longer more descriptive variable name, that would have cost the original developer at worst minutes or probably only seconds.
There seems to be a pervasive, toxic mindset amongst many self-absorbed devs to fix only the problem at hand, leaving a sparse bare-minimum in terms of required explanation of how we do what we do.
With the personality type suited to computer science, there comes a kind of compensatory arrogance that began to form upon leaving the schools where the sporty kids and the popular clique had lorded over us for so many years. Upon entering the ‘Real-World’, we stifled, often ridiculed, frequently rejected by younger society, nerdy, unconfident, socially awkward programmers suddenly had the tables reversed in our favour. We finally realised we were stepping into a world where our skills and talent were finally recognised. Lets face it, even the most humble among us have a mild propensity to believe our intellect superior to that of the mere mortals limited only to the human languages.
But now this sudden burst of ego often fuels an addictive belief that “only I have the mental ability to find these solutions” and that the rest of the team merely stumble in our wake. In truth, future developers working on the same codebase stumble due to a lack of any clues within the code itself as to what it is actually doing, (bad function or variable names,) or lack-lustre comments that don’t adequately explain the WHY of how the code has been constructed. Often I see comment blocks that just explain again, what it is obvious from the code is happening…
// initialise variables let a; let b;
… utterly pointless! These sort of unhelpful comments are usually added just so the developer can assuage their guilt of leaving incomprehensible code. They are unhelpful token statements that were not added from a point of view of wanting to actually help future devs to pick up their work and run with minimum ease, time and effort.
It is this toxic, unaddressed attitude that costs Your Business as additional painful man-hours are wasted, while the original culprit moves on to wreck the lives of the next set of developers to follow in their wake…. but still looking like they are the coding-genius that can pick up other peoples well documented code and solve problems faster than their peers. The more well functioning, elegantly short, but badly documented and hard to understand code they leave behind them, the better they look when compared to their peers.
This belief that BREVITY = ELEGANCE is also something I am vehemently opposed to. Yes, code can always be shorter… but only if that makes it more easily understood. Often it does not. Use of a long descriptive function name that exists everywhere the function is called is far better than a comment that will probably only exist where the comment is declared.
Company Owners, Dev Team Managers and Rockstar System Engineers… I implore you all, stop worshipping at the Altar of Code Brevity. You must abandon this belief! This false god would see your Kingdom in ruins as your armies of coders are consigned to the depths as they search for meaning, obscurity of purpose and elusive solutions in head-scratching, hair-tearing oblivion.
What Coding Style Guide Changes Should I Implement to Save on My Application Development Costs?
Hopefully I’ve outlined and adequately supported my belief that while there is nothing wrong with being succinct, in the world of both front and back end web application development especially, the Quest for Brevity has cost us dearly. This culture is so pervasive and ingrained now that it must be fought. Discourage the use of shortened code that either relies on making assumptions regarding abbreviated words. Also Discourage the use of shortened code that requires instructions in the comments to understand.
Discourage lingo, slang or acronyms. I may be feelin’ the need to use my word-stylez in the articles I write FTW… but I wouldn’t do that to a fellow developer destined to pick up my work in the future…. At least not any more…. unless they ruffled my feathers somewhat…. y’know like parked their car across two bays or didn’t change the loo roll after they’d finished it… I mean, c’mon man, how hard is it to put a new roll on the holder? Sheesh! The existing culture of code minified beyond ease of readability is ubiquitous. Its in almost every example I find on the web. So to encite a culture change in YOUR company’s coding style, needlessly short code must be actively discouraged. The idea that less lines and less characters means increased elegance must be tempered with the overarching goal of your codebase being understandable and maintainable, above all else.
Encourage instead, the use of multiple, simpler lines. Abolish the x , y the temp_c , naming things like currCalc or tot and the many other ways in which proper English words are needlessly shortened by a few characters, so they now save only two extra spaces, but now bring with them ambiguity of meaning and extra mental effort to discern whet they truly stand for. Although these are small mental tasks, they split the focus as the parts of the brain that understand language and interpret words are called upon in addition to the analytical problem solving parts of the brain. This seems trivial, but studies have shown that the more laser focused we are on one task and one task alone, our productivity increases exponentially.
Use the might of the long descriptive variable name that actually says what data is contained within. Use whole words. I even prefer using the more spaced out snake-case popular is iOS languages like Swift. (Controversial: I find underscores more readable and typically only about one fifth longer.)
If a variable is a total… say what it is a total of. While it may be obvious initially to the original programmer… as the codebase expands, and others need to modify a function, or methods or properties within an object / class, I predict with authority that method names like; total_number_of_customers_that_were_quoted_but_did_not_buy will be much more helpful. I use variable names that are as long as this all the time. With the ‘code completion’ feature on by default in pretty much all modern Integrated Development Environments, it really takes no additional time after the original declaration. Yes the code becomes longer, but you know what? On projects that I maintain… ‘future me’ always ends up thanking ‘past me’ when I come back to bug hunt or add a new feature down the road a-ways.
This is a habit I got into when coding ObjectiveC for early iOS app development. When using their extensive supplied code for things like voice recognition or face detection, their factory method names were often insanely long, with full textual descriptions of what the code actually does and without shortening words. Back then, I’m ashamed to say that I also was a disciple of the evil ways of shortening my code beyond succinct. Committing sins I now recognise like nesting nests within nests to save on line and character count. Apple’s immutable rule-set when it came to their coding best practices seemed alien and foreign to me. Their long-winded fully spelled out, always in whole words style of named arguments actually seemed laughable to begin with. But I was crossing a culture bridge, from PHP and JS, (back then, the style was less unified and often even more shortened then it is today,) moving into another camp entirely, the ‘cult of iOS’. While they may dabble, many developers just stick to their preferred area. Even specialising in both PHP and JS, (what I consider to be very similar languages,) back then was referred to as being a ‘Full-Stack’ developer… a accolade that sounds genre-spanning, world travelled and positively multilingual. But iOS… especially in the Original Objective C with all Steve Job’s original NS_this and NS_that cocoa framework functions ported back to Apple from his company NextStep was an absolute world away, also being a complied language, also having to do things like memory management, garbage collections and clearing up pointers. It took a while to get used to. But after a certain amount of pain during what was an almost vertical cliff-face of a learning curve. I found myself with a unique perspective. Being forced to adopt this new discipline meant I had a new appreciation of how spoiled we are on the higher level languages like JavaScript, and PHP with its infinitely flexible variable types (mixed blessing!) But after climbing the mountain to its precipice and finding the mountain-top monastery where monks of iOS worship at the culturally diametrically opposed Temple of Verbose Yet Descriptive Code, I started to see the light. Love ’em or hate ’em, Apple have arguably invested more money than anyone on developing coding standards. (Save for maybe Google, but FaceBook were still running on PHP for around half their lifetime.)
And as anyone who has ever tried to release an App on their App Store will testify… no-one comes close to their level of militant insistence on adopting their standards. Don’t be fooled by the title, Apple’s Human Interface Guidelines aren’t guidelines at all. These ‘suggestions’, as with everything Apple, are absolute texts of religious cannon, the gospel, to be adhered to on pain of death (well… they wait a few weeks and then deny your App release on their store because one of your buttons came a couple of pixels too close to the edge of the screen on a certain device, leaving you with your pants down while you explain to your client why they’ll miss their App Launch Date on iOS and have to wait another few weeks before you get a re-review, back then their approval process was even slower.)
But this unrelenting strictness when it comes to style, has ensured that while the rest of the world got lost in short, in-descriptive code and impossible bug chasing, Apple’s iOS developers always had pre-compiled human readable code that was clear, even without comments. And when Swift came along, they now have code that reads almost like a book.
No question, coding for iOS was harder than building back-end stuff in PHP certainly ‘harder’ than frontend JS. But when I found a bug or needed to troubleshoot why something wasn’t working, I found it comparatively easier to work with longer, more descriptive code.
Partially brainwashed at the church of Apple, I started using their super-verbose style of method and property names in my JS and PHP. I even found that using underscored_snake_case function names over the JS default of camelCasingEachFunctionAndVariable` made it easier to read. Of course i’d never dream of sharing such code on the ‘Stack’… imagine the upheaval and civil unrest as my suggested answer is swamped in downvotes and negative comments give ‘Overflow’ a new meaning.
Finally, where allowed, I started prefixing functions with es_ , I’m not in love with Jobs or anything, in fact I think he was probably a pretty abhorrent guy to know on a personal level and a borderline narcissist, but from a marketing perspective, I really like the idea of prefixing your functions with a short two letter and underscore company id. This also almost removes the chance of accidentally having duplicate function names. Providing I’d originally authored (or at least amalgamated, by mixing hybrid solutions to different interlocking problems, such that they bore little resemblance to any one original function) the es_my_function name convention let me easily see and differentiate which functions I’d actually spent time developing, vs. which I’d used almost wholesale from their original authors, where I’d cite the original URL and author name along with critical descriptive info, should the link break in the future.
Suffice it to say… my code (sans comments) was MUCH longer. Although I felt less need to annotate it. With descriptive Methods and Properties you find your code literally says what it does. As it should anyway. My comments were now almost exclusively limited to WHY I made certain design choices, what something was originally if I had to change it or citing reference and credit where I’d used other people’s code or adapted a solution some benevolent programmer had shared to overcome a similar solution.
People are often very critical of my super-verbose coding style. I know I’m not going to convince everybody here, but what’s the harm in giving it a go on a limited project, with developers you trust, (preferably devs with an open mind, open to change, flexibility in coding style and no axe to grind in the brevity vs. descriptive war… or try finding a unicorn, which is probably more likely.)
Developers Objections to Change You Are Likely to Face
So first off… people will laugh at the dramatically increased line size. Developers somehow have this notion that if it won’t fit on one line then it isn’t comprehensible. This is a question of what you’re used to. Yes, its nice on an assignment operator for things to be split irrefutably to the left (the variable being created) and the right (what gets put into that variable). Its also nice for comparison blocks like we find in if...then conditional statements. But actually, in both these cases, try to stop looking at your program like a mathematics solution, which for comprehension requires additional stages of oversimplification as products_with_expiry is shortened to something liek expProds requiring your brain to needlessly re-interpret this variable name each time it is used. Consider the ‘elegantly concise code’ below…
if (>expProds['expDt']usrExp&&==expProds['stat']"avail") then { ... }
Rather than trying to look at your code as mathematical formulae, which you need to teach your brain to recognise a plethora of abbreviations to understand… instead, try looking at your application code as a story, and read it as such, as words and paragraphs in their original form, following the flow of the words and making use of white-space to do things like break conditionals to multiple lines, like;
if (product_with_expiry['date_of_expiry']>expiry_date_specified_by_user&&product_with_expiry['status_of_availability']=="currently_available") then { ... }
For sure you see that the first example is way shorter… but is it easier to understand at first glance? And is the abstraction of abbreviating the variables not only clouding their meaning, (does ‘stat’ mean ‘status’ or ‘statistics’?), but it also removes you one comprehension level away from understanding what is being tested. Where as the second example is thoroughly explicit in its meaning, and requires no guesswork, or familiarity with the previous programmer’s abbreviations.
The biggest complaint I get, most push-back, highest resistance is regarding the increased time spent typing. However, with code-completion (or by copy-pasting, as I always intend the devs I manage or my students to do when I teach, from supplied resources,) after getting over the initial culture shock, I found it a much better experience to have the code itself actually explain what it is doing, removing the need to add a comment on every line saying what it does. Kyle Simpson, (personal hero of mine,) says that a comment should only be added to say WHY something is being done. The code itself should say WHAT and HOW it is being done. Please don’t by typing any of this in by hand, believing it’ll make you learn it better. READ to learn, COPY-PASTE to create, THEN edit to personalise, before you hit return to execute the line. Although it looks cool in the hacker-movies, in reality, manual typing does nothing other than introduce human error to your code. Make [cmd + c] and [cmd + v] your best friends. This scratches the surface of an age-old debate on optimised code brevity vs. explicit descriptive code, which continues to rage on to this day.
Nowadays, in almost any modern language, (yes even scripted languages like PHP and JavaScript,) with each new version revision, computer language code compilers are always optimising the code you write, before it is ever run by a machine, (JS and PHP have a ‘parse phase’) removing the need for us to be thinking in terms of “How to I make my code shorter?” or “Which version of the code will run fastest?”… these are the wrong questions. Instead ask “Will this be a familiar design pattern?” if so the compiler will be able to look for it and future versions of client-side browsers, server-side languages and compiled languages like Apple’s Swift will be able to optimise for it. In case you haven’t guessed by now I fall firmly in the “Be as Verbose as you like to aid in comprehension” camp on the side of this argument, and have been for time. And after suffering years of unpopularity with other devs and missing out on being invited to all the really cool parties, finally things are starting to swing our way as the in-vogue but indecipherable, lets fit everything into one line with variable names only a CPU will understand, is finally giving way to a new era of writing much longer code, that reads like a human written book, actually says what it does, and always takes less time to understand, despite its sometimes 10x increase in character length. Perhaps you’re a sadist working within a team that enjoys seeing your colleagues perplexed as they try to decipher your latest antikythera mechanism function, when they need to pick up from your work? Even if you’re not… be kind to yourself. I can’t tell you the amount of times I’ve come back to a code repo that I worked on myself only weeks before, but have totally forgotten how the hell I built it. Even though it works, leaving clues in the actual code to your future self as to WHAT your code is doing, and exhaustive comments as to WHY you built it a certain way will shave years of coding despair and coding woe from your life. Also, for the love of god.. timestamp your comments and updates in the actual codebase, with your unique initials, (on any project, unless conforming to existing coding style guides, I always date and initial ALL my comment blocks, with company initials / individual initials, and date of comment. So Energise Studios James Forbear with a human readable date-time rather than UNIX timestamp, like ESJF 2023-02-14 for the work I completed on Valentines Day, while everyone else was on a romantic date… the only dates I was privy to ended up in a well documented codebase ; – ) and please don’t date-stamp in a way that normal humans have to leave the UTC converter tab open on their browser.
(I know that the die-hard, partially cybernetic, Trekkie, sci-fi nerds among us have all calibrated our brains to know at any given moment the number of seconds since Jan 01 1970… but come on, must we insist that every other future programmer following us also use this StartDate system?)
By using a normal YYYY-MM-DD format, any human can know at a glace which bit of code was added when. And with nice long descriptive comments, avoiding acronyms and word shortening, they will know why and for what feature, without having to have a million screens open comparing the diff(s) of multiple version updates. Version control like GIT is great, but I prefer it as a fallback, not the ONLY version of what was done when, by whom and why.
Also consider, as a policy, commenting out and leaving a copy of the original code prior to the last update, either above or below the change itself, (choose one and stick to it!) It won’t affect or confuse your ‘diff’ because version control will just see it as a comment block. But in the event of rolling back a change, or hunting down unforeseen bugs it has introduced, having the original right there in the codebase can be a real time-saver.
Yes, I know… implementing these ideas will mean your codebase will be significantly larger and longer, but time taken scrolling to the relevant bit to update is trivial, as is storage space with all the advances in data capacity on physical media. The cost increase is negligible. What DOES end it costing large is your developer’s billable time, as they cross-reference and hunt down exactly which change was made when and why in your version control system before they can even start working on it.
Adopting a long term verbose and descriptive coding style change
I’ve tried it, I like it. We’re developing faster… but how do I maintain these ‘abnormal’ style guidelines as future developers come and go?
Catch someone doing something right and applaud them. Make sure they are recognised by the team. After a while your company culture will take on these ideals as their own.
It is a better way to work. But only experience of this will convince your team. Try to have a de-brief after mini-updates to discuss whether it was easier maintaining a more descriptive codebase. By bringing it to your team’s attention, they will acknowledge that descriptive and increased length but explicit names means more readable code. I’ve been doing this for long enough now to be assured that, in spite of inevitable early resistance from the more human-computer among us even with the most basic web application… it just is better.
Bugs are fixed faster. Features are added with ease. Everyone gets down the pub earlier ;P
In the Studio with Cargin Moss
