How to name software things, be a good programmer & work solo

My TL;DR style notes from articles I read today.

Effectively Naming Software Thingies

“Programs are meant to be read by humans and only incidentally for computers to execute”
— Donald Knuth

• Write intent revealing names. If the variable stores the last updated record, name it ‘lastUpdatedRecord’, not just ‘record’, or even ‘lastRecord’
• Make clear distinctions. What kind of info will ‘ProductInfo’ has that the ‘ProductData’ won’t?
• Add context to names. Put variable state in well-named classes.
• Don’t abbreviate. Say ‘getWindow’ not ‘getWin’
• Pick one word per abstract concept & stick with it. Using both fetch and retrieve will cause confusion. Pick and use only one.
• Don’t pun, don’t make your readers mentally map names to something else.
• Use conventions for common operations.
• Avoid similar sounding & easily misspelled names.
• Favor readability over brevity.

Full post here, 7 mins read

---

What Makes a Good Programmer?

• Problem decomposition

  “…there are very few inherently hard programs. If you are looking at a piece of code and it looks very hard – if you can’t understand what this thing is supposed to be doing – that’s almost always an indication that it was poorly thought through. At that point you don’t roll up your sleeves and try to fix the code; you take a step back and think it through again. When you’ve thought it through enough, you’ll find out that it’s easy“.
  - Bernie Cosell

• Scenario analysis: Good programmers always ask themselves - how can this break?

• Naming things well

  “There are only two hard things in Computer Science: cache invalidation and naming things.”
  - Phil Karlton

• Consistency: Consistency across your programming practices allows you to concentrate on essential complexity & and not accidental complexity.

• Continuous learning about the developments in software engineering

Full post here, 5 mins read

---

Good Engineering Practices while Working Solo

When you are working solo, you are filling multiple roles on a project. Following these practices help with a good outcome:

• Stick to a workflow
• Organize & share components
• Write documentation
• Monitor
• Observe & iterate
• Communicate regularly with the rest of the team/client

Full post here, 11 mins read

---

I share these TL;DR versions of articles on software engineering that I read every weekday through my newsletter - in.snippets(). Sign up here if you liked what you just read.

Comments

[Evaldas Buinauskas]

I've recently made a change in our api where we had three data properties where each meant totally different thing. 🤔

[Arpit Mohan]

Are they now named data1 , data2 and data3 ? 😛

[Evaldas Buinauskas]

No! : ) It is paginated research data and JSON previously looked like this:

{
    "page": 1,
    "size": 3,
    "total": 3,
    "data": [
        {
            "countryId": 1,
            "categoryId": 2,
            "data": [
                { "year": 2012, "data": 123.45 },
                { "year": 2013, "data": 123.45 },
                { "year": 2014, "data": 123.45 },
                { "year": 2015, "data": 123.45 },
                { "year": 2016, "data": 123.45 },
                { "year": 2017, "data": 123.45 }
            ]
        }
    ]
}

Now it's been renamed to be as follows, which is 1000 times better!

{
    "page": 1,
    "size": 3,
    "total": 3,
    "results": [
        {
            "countryId": 1,
            "categoryId": 2,
            "timeSeries": [
                { "year": 2012, "value": 123.45 },
                { "year": 2013, "value": 123.45 },
                { "year": 2014, "value": 123.45 },
                { "year": 2015, "value": 123.45 },
                { "year": 2016, "value": 123.45 },
                { "year": 2017, "value": 123.45 }
            ]
        }
    ]
}

[Simon Newby]

I'm feeling bad about the database I tossed up last week where all the ID columns are called ID rather than <tablenameID now... 😳

[Arpit Mohan]

I actually prefer that instead of tablenameID. I typically don't like alliteration in my SQL queries or code function calls. I'd much rather invoke select * from users where id = ? instead of select * from users where userid=?

I find the first one more readable and understandable as well.

[Evaldas Buinauskas]

This isn't generally bad. I worked with both and having TableNameID makes a lot of sense when you write more SQL code. It makes join conditions way easier to read.

[Simon Newby]

Yeah definitely, and since I'm using the ids to correspond to other numeric columns in one base table then using a view to display strings instead of underlying integers, I think it's passable for the time being.

[Daniyal]

It seems pretty okay for a database since the context gives it meaning and using 'id' is pretty common in database lands. i.e. don't feel bad!