Programming: Practices of a (Less) Pragmatic Programmer

Disclaimer: I haven't read the book The Pragmatic Programmer yet but the book seems to go beyond the practices I recommend. Hence I settled for calling these the practices of a programmer who is "less pragmatic."

TLDR: Document everything, communicate better, write good commit messages, and be a good coworker. 

I've been thinking lately about why I do my job the way I do. Why do I perform my tasks the way I do? I can't really pin down to one solid reason. Maybe through hearing about them or my careful, thorough personality, these work habits just naturally materialized. Whichever the case, they make sense to me, especially in my work environment.

To frame your point of view, some key highlights about my work environment are:

• Complex and (many times) unclear requirements: We have a pretty sizable, complex set of requirements on a product that's about 15 years old. User stories often get fleshed out while the developer is implementing them. 
• Resource-constraint: Let's face it. Most teams are short on resources. However, it should be said that our team is pretty lean and agile. It's a core team of 7 developers and 3 QA analysts serving an application that brings in 7-figure yearly revenue. Currently, I'm the only front end developer.
• Big legacy application: I inherited a very old and technical-debt heavy front end codebase, with some bright spots from my recent predecessors. 

Hopefully, these practices I arrived at (and probably stole from other places) help you deal with some of the bullet points above.

1. Document everything

Documenting and writing everything down will help you do the following:

Remember

To me, this is the most important benefit of documenting. Many times, someone will ask me to do something and I make a new JIRA ticket and describe what needs to be done. I no longer need to remember the details because it's now a part of my queue of tasks and the details have been recorded. Later, my brain doesn't need to figure out what I was supposed to do or who said what.

Common questions and answers? Commonly used strings or urls? Any commonly referenced information goes in a text file on my Desktop called "common.txt". 

My mind no longer needs to remember things and can devote more energy to stuff that really matters, like the parts of your job that actually requires your problem-solving skills. It also saves time from having to dig through old emails/messages or hunt down people to get the details again. 

Provide clarity

When writing software, there will inevitably be the need to ask questions or get clarifications on business requirements. Or one stakeholder might have a different interpretation of the acceptance criteria than another. I've definitely encountered instances where I implemented a feature one way from verbal discussions and the QA team expected something else from written requirements. Then we have to get in touch with the business team or product owner to clarify things.

Nowadays, if there's changes in requirements discovered during development, I don't wait until the AC's are updated in the user story. I add a comment in the JIRA ticket that goes something like this: "From 12/15/17 standup, @MentionProductOwner confirmed Feature X should behave like this." This has saved many hours at my company because our product owner is very hard to get a hold of and often requirements are modified during development.

Hold people and yourself accountable

Have you ever had someone tell you something one day and then turn around the next day and say something completely different? Many times, it happens inadvertently with no ill intentions. Memories get misremembered, questions get misheard, and comments get misinterpreted all the time. Other times, the darker side of office politics pokes its head out.

Whatever the case, it often helps to send out a quick email or a comment in the JIRA ticket to summarize what was said and discussed. This action solidifies what happened and acts as a quasi-contract with the parties involved. Now you have something to reference in the future if accounts of the past don't match.

2. Communicate better

Get to the point

In your communications, get to the point quickly. Give just enough information for them to understand the context and the important details. If they need more details, they will ask for it. It's important to recognize their minds have probably been deeply tangled with their own tasks so they won't have the context and working knowledge you have so don't flood the communication channel with details that can detract from the main point.

Sometimes, I will start an email with the summary or T.L.D.R. (too-long-didn't-read) bullet points. I also recently learned of a communication technique called S.T.A.R. which is acronym for Situation-Task-Action-Result. You describe the situation at hand and/or the task you were given. Then you describe your actions and the results of the actions. It's an executive summary in three or four sentences. It's a great starter to lead into longer conversations and discussions.

Screenshots and highlighting

Nothing is better than a screenshot with the important detail circled or underlined with a bright color. I have Greenshot installed on all my PCs and laptops. It allows me to quickly screen-capture any area on my screen. If desired, I can open it in the program's image editor and highlight text or circle the important part of the screenshot.

See, much clearer to communicate, "I'm talking about that icon!"

Written - Bold, underline, and punctuation marks

Most messaging apps/programs allow for bolding and underlining. Some even allow for custom colors and monospace font (eg for code snippets)! These are great ways to put emphasis on phrases or help convey your intentions and thoughts. There's no way to change the tone heard or the speed of your communication like you can with verbal communication. Bolding and underlining help add color to your written communications.

IMO, punctuation marks are severely underused, especially in the post-iPhone-1 world. First, commas are sorely missing in compound sentences, to add describing fragments, and to indicate addressees (eg "Chai, can you do this?"). P/S: I'm also a fan of the Oxford comma. Second, I find parenthesis are awesome for adding supporting, secondary information that help provide clarification to the main point of sentences. Third, dashes can be used to provide emphasis on a word or phrase. Multiple dashes together can be used to define boundaries or a dividing line between sections. This is just barely puncturing the surface of punctuation marks..

3. Write good commit messages

Whether you use git or SVN for version control, you will write messages that go with your code commits. It's easy to just write some vague message but you will eventually regret it when you are refactoring code or trying to understand code between a team of developers (or even code you wrote last week!). I've spent more time than I like staring at code diff's and commit messages made by developers that have long left the company trying to decipher requirements or why code was written. Having the original ticket number always expedites the process and provides context for the code changes. 

For the sanity of you and your team, please write good commit messages! If your team doesn't depend on the commit message being a certain format (like Angular's code repository which generates change-logs from the commit messages) and are looking for a suggestion, here what I do:

"[TICKET-#] Global Toolbar - Menu. Add link to help pages." 

It has the ticket number, the feature or area of application affected, and what the code commit will do when applied to the code (which is stated in the present tense). Especially in a big, old code base which often needs refactoring, this practice provides a nice boost in productivity.

4. Be a good coworker

It helps your career a ton if everyone enjoys working with you. To me, this practice goes beyond the normal expectations, like manners, friendliness, and hygiene. 

Integrity

The quality I admire most in people is integrity. It's the foundation upon which society is built upon. You practice integrity on the road by following the traffic laws; the fact that most people follow the speed limit and obey traffic lights assures you that you can drive and get to your destination safely. It extends out to most areas of life, from the social contracts of relationships and agreed cultural norms to the salary you get paid for the hours your work. 

If you say you will do something, do your best to adhere to your commitments. It builds credibility and shows your coworkers you are dependable. Of course, you can't be perfect and always meet your targets. You will make mistakes, sometimes big blundering ones. Mistakes are okay; what's not okay is not owning up to them. I'm not saying call people out but rather if you make a mistake yourself, own up to it. Acknowledge your mistakes and learn from them. 

Help others

Luckily, I've always ended up with amazing coworkers that answer any questions I have about technology or life. If you're still early in your career, you might not have as much to offer to your coworkers. I find it helps to take initiative in filling the needs of others. For example, if one team member is getting swamped with work, offer to look into some of their tickets for them. Or if someone has a question that you might know how to Google the answers for, help them investigate. I've learned many new things and expanded my skills from doing this. 

Nowadays, being the only front end developer and having helped solve many problems on my team, I often get incoming requests for help than the other way around. I guess I'm paying my dues now but I do it gladly because I get to learn, expand the breadth of my knowledge, and the amazing satisfaction of solving tough problems. In return, people are always willing to help me out with my questions or problems. The team also has a better camaraderie and atmosphere. All in all, the reciprocating effect and cycle of helping each other out makes a huge contribution to the team's effectiveness and overall success. 

Conclusion

To summarize, my practices of a "less" pragmatic programmer are:

1. Document everything in tickets, emails, or even on paper.
2. Communicate better by getting to the point fast, taking screenshots, and using bold/underline and punctuation marks.
3. Write good commit messages (include the ticket number).
4. Be a good coworker by having integrity and helping others. 

I have more but the snow has just stopped and I need to get home... I'll save them for a Part-II post!