SW Construction: Java Coding Conventions (by Google)

The short story

Here are the Google Java Coding Conventions. made to be easily understood and enforceable (automatically), they are a good insight on what a big company defined as best practices for coding on a certain (widely popular) language:

https://google.github.io/styleguide/javaguide.html

Quoting:
"Google's coding standards for source code in the Java™ Programming Language. A Java source file is described as being in Google Style if and only if it adheres to the rules herein.

Like other programming style guides, the issues covered span not only aesthetic issues of formatting, but other types of conventions or coding standards as well. However, this document focuses primarily on the hard-and-fast rules that we follow universally, and avoids giving advice that isn't clearly enforceable (whether by human or tool)."

Is your project following any best practices at all? Are they written? Who wrote them? Do you use them at will or is there someone who enforces them? If the answers to those questions are not clear on your mind, read the long story below.

The Long Story

Your company, your department (Domain Expert, CTO, etc.) or even only your PM and TM could define as coding conventions some external document (or standard) to follow during project execution. The advantage could be that you are reusing (documentation) - and thus saving money - as well as saving you - or your team / department - the hassle of keeping it internally updated. 

The other advantage is that, if rightly chosen, nobody will question the authority of such a document (while an output of former teams, projects and/or internal experts) could suffer from that lack of authority and general trustworthiness by everyone involved.

Enforcing the coding standard (coding conventions) into a tool like CheckStyle (that could be inserted as an integration task in the Continuous Integration server) is also a good idea because early deviations will have to be fixed by the team (you could make the build fail if a rule - even a formatting one - is broken). 

Updated: 2018-01-07, short and long story.

BOOK: C++ Coding Standards: 101 Rules, Guidelines, and Best Practices (Herb Sutter, Andrei Alexandrescu)

Amazon.com: C++ Coding Standards: 101 Rules, Guidelines, and Best Practices (9780321113580): Herb Sutter, Andrei Alexandrescu: Books

Quoting:
"Consistent, high-quality coding standards improve software quality, reduce time-to-market, promote teamwork, eliminate time wasted on inconsequential matters, and simplify maintenance. Now, two of the world's most respected C++ experts distill the rich collective experience of the global C++ community into a set of coding standards that every developer and development team can understand and use as a basis for their own coding standards.

The authors cover virtually every facet of C++ programming: design and coding style, functions, operators, class design, inheritance, construction/destruction, copying, assignment, namespaces, modules, templates, genericity, exceptions, STL containers and algorithms, and more. Each standard is described concisely, with practical examples. From type definition to error handling, this book presents C++ best practices, including some that have only recently been identified and standardized-techniques you may not know even if you've used C++ for years. Along the way, you'll find answers to questions like

• What's worth standardizing--and what isn't?
• What are the best ways to code for scalability?
• What are the elements of a rational error handling policy?
• How (and why) do you avoid unnecessary initialization, cyclic, and definitional dependencies?
• When (and how) should you use static and dynamic polymorphism together?
• How do you practice "safe" overriding?
• When should you provide a no-fail swap?
• Why and how should you prevent exceptions from propagating across module boundaries?
• Why shouldn't you write namespace declarations or directives in a header file?
• Why should you use STL vector and string instead of arrays?
• How do you choose the right STL search or sort algorithm?
• What rules should you follow to ensure type-safe code?
• Whether you're working alone or with others, C++ Coding Standards will help you write cleaner code--and write it faster, with fewer hassles and less frustration."

SW Construction: Guidelines / Coding Conventions

Coding guidelines:
http://www.dotnetcurry.com/software-gardening/1333/coding-guidelines-important-for-developers

BOOK: The Practice of Programming - B. Kernighan | Rob Pike

By no-one else than Mr. Kernighan (from the Kernighan & Ritchie book you might have heard of), "The Practice of Programming" is a 1999 book on best practices while programming and more:

FFR here is the Amazon link with additional information on the book: https://www.amazon.com/Practice-Programming-Addison-Wesley-Professional-Computing/dp/020161586X/ref=sr_1_1?s=books&ie=UTF8&qid=1479759220&sr=1-1&keywords=the+practice+of+programming

Quoting:
"With the same insight and authority that made their book The Unix Programming Environment a classic, Brian Kernighan and Rob Pike have written The Practice of Programming to help make individual programmers more effective and productive.

The practice of programming is more than just writing code. Programmers must also assess tradeoffs, choose among design alternatives, debug and test, improve performance, and maintain software written by themselves and others. At the same time, they must be concerned with issues like compatibility, robustness, and reliability, while meeting specifications.

The Practice of Programming covers all these topics, and more. This book is full of practical advice and real-world examples in C, C++, Java, and a variety of special-purpose languages. It includes chapters on:

• debugging: finding bugs quickly and methodically
• testing: guaranteeing that software works correctly and reliably
• performance: making programs faster and more compact
• portability: ensuring that programs run everywhere without change
• design: balancing goals and constraints to decide which algorithms and data structures are best
• interfaces: using abstraction and information hiding to control the interactions between components
• style: writing code that works well and is a pleasure to read
• notation: choosing languages and tools that let the machine do more of the work

Kernighan and Pike have distilled years of experience writing programs, teaching, and working with other programmers to create this book. Anyone who writes software will profit from the principles and guidance in The Practice of Programming ."

DIGEST: SW Construction - Further Reading

Additional Resources for SW Construction:

While building your software (aligned with the gathered requirements - SRS - and the software design that your high-level architecture defines - SAS) several additional topics are relevant. For instance: Coding standards to comply with (if any); comments to create and % of comments and eventual traceability to requirements IDs / component ID there left; static analysis to perform (and extracted KPIs to comply with - if any); continuous integration server and tasks to use; verification measures such as unit tests, code reviews. For more generic information on these topics see here.
   
For further detailed information please see the following links (some are INTERNAL).

Static Analysis: 

1. http://silvaonsoftware.blogspot.pt/2016/05/tools-source-monitor-static-analysis.html
2. http://silvaonsoftware.blogspot.pt/2016/05/tools-static-analysis-tools-listing.html
3. http://silvaonsoftware.blogspot.pt/2016/10/sw-construction-static-analysis-tools.html

Code Reviews: 

1. The QMS context (INTERNAL): Review Procedure here; Crucible Tool GBK here; CheckStyle (Java) tool GBK here.
2. Code Reviews example - Crucible (Plugin to JIRA; INTERNAL): https://crucible.critical.pt/cru/ATG-5#CFR-11408

Continuous Integration (CI):

1. About CI, a list of several servers available can be seen here: https://en.wikipedia.org/wiki/Comparison_of_continuous_integration_software
2. Example - Jenkins (INTERNAL): http://jenkins.critical.pt/computer/(master)/ (INTERNAL; Teamcity could also be in use for some projects).

Unit Testing: 

1. Think "developer tests" (and see Module 9 for now; again, INTERNAL)

Further reading - Coding Standards: 

Each company might have internally defined coding standards. Or it could be using external standards (e.g. HP, NASA, ESA, etc.). Google for "C Coding Standard" and see what it is meant by coding standards here: For instance this is 1994 NASA-SEL's style guide for C (PDF).

Further reading - BOOKS: 

There are lots of books on SW Engineering that focus on best practices for coding activities, with the objective of writing clearer code, easier to understand and maintain, easier to reuse, etc. 

Two must read examples might include: 

• Clean Code - Robert C. Martin, 
• Code Complete 2 - Steve McConnell

Many more books have full chapters on writing "good" code. 

Again, "Google" and/or "Amazon" for it.

Happy readings!