https://DevOpsCloud.io -- Cloud Monk Losang Jinpa

Programming Best Practice

Return to Programming Style Guides, Software Engineering Best Practices, Software Architecture Best Practices, Clean Code, Pragmatic Programmer

Below highlights universal best practices applicable to programming in general, focusing on principles that enhance programming code quality, programming maintainability, programming performance, and programming security. This summary will touch on key concepts without diving into language-specific syntax but will include examples where appropriate.

Programming best practices are guidelines that developers follow to produce clean, efficient, and error-free code. These practices are essential for enhancing the maintainability, scalability, and performance of software applications. While practices may vary across different programming languages, the underlying principles often remain consistent.

Choosing descriptive and meaningful names for variables, functions, and classes makes your code more readable and maintainable. Names should convey to the reader what a variable holds, what a function does, and what a class represents.

Each function or method should perform a single responsibility. This simplifies testing, debugging, and understanding the code, adhering to the Single Responsibility Principle (SRP) of the SOLID principles.

Aim to write reusable functions and modules. This reduces redundancy, minimizes the risk of errors, and facilitates easier updates. Reusability can be achieved by generalizing the code to handle various inputs and scenarios.

Comments and documentation are essential for explaining the purpose and logic of your code, especially for complex algorithms. However, comments should not be used to explain bad code; instead, strive to make the code self-explanatory.

DRY (Don't Repeat Yourself) emphasizes reducing repetition in your code. Repeated code should be abstracted into reusable functions or modules, making the codebase easier to maintain and update.

Version control systems, such as Git, are crucial for managing changes to the codebase, enabling collaboration, and tracking the history of your project. They facilitate branching, merging, and revert operations, enhancing team workflow and backup strategies.

Following coding standards and style guides for the programming language you're using ensures consistency across the codebase. This practice improves readability and reduces the learning curve for new team members.

Code is read more often than it is written. Optimizing for readability means organizing your code logically, using consistent indentation, and following the language's idiomatic conventions.

Robust error handling mechanisms improve the reliability and usability of your software. Catch and handle potential errors gracefully to prevent the application from crashing unexpectedly.

Security should be a priority from the start. Follow security best practices such as validating inputs, using secure communication protocols, and adhering to the principle of least privilege.

Choosing the right data structures and algorithms for the task can significantly impact the performance and efficiency of your application. Understand the time and space complexity of your implementations.

Code reviews are a valuable practice for ensuring code quality, sharing knowledge, and catching potential issues early. They encourage collaboration and learning among team members.

Automated testing, including unit, integration, and functional tests, helps ensure your code works as expected and facilitates refactoring and updates. A solid test suite acts as a safety net for changes.

Refactoring is the process of restructuring existing code without changing its external behavior. Regular refactoring improves the design of the codebase, making it easier to understand and extend.

Spend time understanding the problem you're trying to solve before jumping into coding. A clear understanding of the requirements and constraints leads to more effective and efficient solutions.

A good plan outlines the major components of your solution and how they interact. This can prevent significant rework and ensure the architecture is solid and scalable.

The tech industry evolves rapidly. Staying informed about the latest trends, tools, and best practices in your field can open up new opportunities for optimization and innovation.

While performance optimizations are important, they should not come at the cost of readability and maintainability. Premature optimization can lead to complex, hard-to-maintain code.

Simplicity is key to good software design. Avoid over-engineering solutions and keep your code as simple as possible while fulfilling the requirements.

Be open to changing your code based on feedback from code reviews, testing, and user input. Adapting to change is a vital part of the development process.

Design patterns provide generalized solutions to common design problems. Using them wisely can help structure your code in a more scalable, reusable, and maintainable way.

Consider

the end-user experience in every aspect of your application, from the UI/UX design to the responsiveness and performance of your software.

A strong development culture encourages continuous learning, collaboration, and a focus on quality. It's essential for building effective and motivated teams.

A deep understanding of your development tools, including IDEs, build systems, and debuggers, can significantly enhance your productivity and the quality of your output.

CI/CD practices automate the integration, testing, and deployment of your code. They help maintain code quality and speed up the release process.

Regularly monitor your application's performance in production. Use profiling tools to identify bottlenecks and optimize as necessary.

Be mindful of data privacy laws and ethical considerations when handling user data. Implement proper data protection and privacy measures.

Sustainable coding involves writing energy-efficient code and considering the environmental impact of your software, an increasingly important aspect of software development.

Participating in programming communities can provide support, inspire new ideas, and keep you informed about best practices and emerging technologies.

View failures as learning opportunities. Analyzing mistakes helps improve your problem-solving skills and resilience.

Make your applications accessible to as wide an audience as possible, including users with disabilities. Accessibility is not only ethical but often a legal requirement.

Always consider the ethical implications of your work. Responsible programming involves ensuring that your code and applications benefit users and do not harm society.

Design your systems to handle growth, both in terms of users and data. Scalable architecture ensures that your application can meet future demands.

Maintain comprehensive documentation for your code, APIs, and systems. Good documentation is invaluable for onboarding, maintenance, and future development efforts.

This summary encapsulates core programming best practices that transcend specific languages and technologies, focusing on principles that lead to high-quality, maintainable, and efficient software. For language-specific details and further exploration, consult the official documentation and resources dedicated to your programming language of choice.

Git Best Practices:

• 1 git commit per change, do squash on git merge
  • you can easily work with git changes

• There might be few (already squashed) git commits in a GitHub pull request
  • don't make huge git changes they will bury the truth

• Touch few things at once
  • it's kind of obvious

• git rebase instead of git merge
  • no git merge commits, cleaner git history

• GitHub pull request must have at least 1-2 approvals
  • changes must be visible to the team members

• GitHub master is git read-only
  • it's a rule. Always. No exceptions.

• git delete git branches after a git merge
  • better git navigation and git performance

• Use SemVer as a standard for versioning
  • Do not reinvent the wheel

• git release tags
  • git tracking releases/ git deployments are simpler

• Omit git release branches for patches (aka 0.1.x)
  • use git release tags for that

• No git global history changes
  • Prevents git history misuse

• git commit message format
  • Clear, well explanatory, structured

• No big GitHub binary files inside a GitHub repo
  • Slowdowns without a reason

• Have a meaningful GitHub README
  • So everyone can quickly get an overview of the GitHub repo

Continuous Integration CI Best Practices:

• Auto-revert on failure
  • CI/CD rollback changes, no broken code in the git master

• Run at any git commit
  • The obvious ability for CI

• CI plan in ]]git]]
  • know all plan changes and have consistency

• Warn about formatting verification
  • No developer disruption in the future

• warn about coverage illness
  • coverage is a quite important thing

• track test failures and flakiness
  • statistics, hints, conclusions

• store build logs for 3+ months
  • having analytics and working links to them

• do not remove builds/PR/issues
  • unexpected 404 will help no one, will not save disk space also

• docs are generated from the code
  • end-user changes must be explicit

• locally reproducible builds
  • re-run part of a job on my local machine

• use Makefile, Bash
  • simple, easy, well known

• ability to start/stop a job on CI
  • waiting for an approval to make this action is a horrible bottleneck

• CI jobs should be ran periodically
  • to reduce possible errors due to hidden dependencies - See Dependency Management Best Practices

See Continuous Integration vs. Continuous Delivery vs. Continuous Deployment

• Continuous Delivery CD Best Practices:
• Continuous Deployment CD Best Practices:

• configuration files must be validated before a start
  • unless difficult debug is your goal

• store config in the same repo as a code
  • this prevents 'the chick or the egg' problem

• all features must be protected by feature flag
  • in case of an accident, it will(might) be enough to turn it off

• deployment of a new config must be isolated
  • to separate different machines/containters/storages from each other

• deploy must go from a (git-)tag or release, not from the master
  • this restricts a changeset which will be deployed

• Code Health Best Practices (see also Refactoring Best Practices):

• leave your code better than you found it

• document your code
  • giving a small context for API will save a lot of time

• use linters and code analysis all the time
  • the best handling for the best code

• touch legacy, often
  • it becomes non-legacy faster

• remove deprecated stuff
  • having a bloated dead code is a mistake

• also remove old code
  • it adds even fewer reasons to the new code

• use TODO, BUG, XXX in code
  • jumping to the issue tracker can be minimised

• no experiments in the master
  • use your 20% time as a playground, please

• allow changing log-level on the fly
  • this will simplify production's debug routine

• limit your log file, 'cause it might grow unlimited
  • this might cause troubles to your app, be careful

• store your config in /etc/myapp and logs in /var/log/myapp
  • this will make everything more structured and well defined

• all modules must have the same structure
  • similar environment everywhere is a good idea

• if you can’t show a bottleneck, don’t start to optimise it
  • it might be interesting and challenging, but useless

• check back compatibility before the new releases
  • make it explicit and obvious (+doc how to port)

Database Best Practices (see also Data Science Best Practices:

• think about your data
  • don't use SQL/NoSQL without a reason

• keep models normalized
  • less storage, better performance

• but don't normalize without a reason
  • everything is a trade off

• use timestamp to store a date/time
  • this will save you from formatting hell

• log slow queries
  • see what is happening in a database and who is too greedy

• don't put business logic into DB or at least make it loosely coupled
  • this will give you an easy migration to another DB

The most important task of a programmer is dependency management! (see latest Manning book MEAP) Dependency Management Best Practices:

• Thoroughly analyze all of your service’s dependencies

• wrap any dependency with an interface(or analogue)
  • this will prevent a vendor lock on it

• bump libs on a permanent basis
  • the new version is expected to be better

• have a local cache-server with dependencies
  • adds stability to the infrastructure

• pin your dependencies to a specific version
  • accidental commit to dependency's master will break nothing

• prefer mature technology, rather than a hyped one
  • mature will die slower, then hyped

• fork instead of hack
  • it might be better to fix a lib instead of wrapping for the desired behaviour

• use one test framework
  • a similar environment is better

• show results, not just stack traces
  • some failures are obvious with visible result

• isolated tests
  • use beforeTest and afterTest aggressively

• TDD
  • it really works

• measure a code coverage
  • a quick and easy way to eliminate bugs

• test your backups
  • they might be broken

• do not hard code ports in tests
  • unless you're interested in random flaky tests

Teamwork Best Practices - Team Best Practices:

• pairing, 50% and more
  • you're doing better, you're not bored

• high-level stand-ups, time bounded
  • less info about irrelevant stuff

• 2-3 week sprints
  • have an achievable sprint goal
  • UPD: depends on team/project, might be unuseful

• per sprint roles
  • it's quite comfortable time bounds

• only urgent topics are face-to-face
  • fewer distractions for unimportant things

• friendly atmosphere
  • no insulting environment, respectful trolling

• 'coding rockstar'
  • it is a demotivation, not an inspiration

• if you're on the vacations - specify a date range
  • it'll be easier to find someone else or postpone the question

• FAQ for newcomers
  • 30-day plan with all stuff that they should accomplish

• document solved and unresolved problems
  • team members will be aware of some problems and it will be resolved much faster

• every ticket in progress must have an assignee
  • this prevents doing same work on one task

• there must be a run book or guide for every responsibility
  • 30/60/90 days plan for newcomers, guide for on call, support

Meeting Best Practices:

• I can skip if I'm out of scope
  • do not waste team and own time

• if you're organizing a meeting - prepare an agenda
  • to have a way how to drive a meeting

• action points after the meeting
  • who does what and when

• avoid bus factor as much as possible
  • moving/cancelling an unimportant meeting because 1 person is a bad sign

Communications Best Practices:

• use the best apps
  • fast, flexible, pleasurable

• outcomes of important discussions should be on a wiki
  • better visibility for outcomes

• only important notifications
  • @all should be rare for irrelevant updates

• easy access to any team room
  • that's obvious, hey

• do not delete personal chats with inactive users
  • some chats contain interesting ideas

• closed ticket must contain a link to the changes
  • every change must be easily accessible and visible for others

Permission Best Practices and Security Best Practices:

• Git, CI, SSH read-access to everything
  • reading server logs cannot cause troubles

• SSO to anything
  • better organization of credentials

• each office should have global admin
  • different time zones are a bottleneck

Workspace Best Practices:

• engineers apart from non-engineers
  • fire & ice

• quiet open-space
  • someone might be sensitive to noise…

• quiet zones
  • …really sensitive
• the kitchen isn't for chill-out

** the playroom is a thing

• nothing smelly near working area
  • even coffee/cinnamon/mowed grass might irritate

Networking Best Practices:

• VPN access from home
  • work from home is a cool thing

• WiFi must work all the time
  • obvious

• LAN must be even more stable
  • uber-obvious

Life Best Practices:

• how often should my salary be reviewed?
  • worth asking

• work from home is a must have
  • family, health, even weather might be a reason

• educational budget to anything related to dev stuff
  • I would like to learn new technologies, why not?

• allow committing to the open-source
  • company karma++

• skipping team events must be acceptable
  • well…obvious

• 20% time is a vacation like time
  • creating anything that might help someone is awesome

• brown bags sessions must be rewarded
  • sharing knowledge is the best way to inspire

• monthly geek swag <3
  • t-shirts, hoodies and all other stuff

• health food in the kitchen
  • candies are cool, but I would like to live longer

Fair Use Sources:

• Agile Manifesto
• Zen of Python
• Clean Code
• Pragmatic Programmer
• https://github.com/AzureCloudMonk/awesome-developer-manifesto - GitHub fork of https://github.com/cristaloleg/awesome-manifesto
• Software Mistakes and Tradeoffs - How to make good programming decisions by Tomasz Lelek and Jon Skeet