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.

SW Construction: Guidelines / Coding Conventions

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

SW Construction: Checkstyle in Eclipse

The short story

Checkstyle is a static analysis tool with an Eclipse Plugin (it also has a Maven plugin), that allows you to... check style. An excellent article describing how to install, configure for a project and run for reporting (things about style, duh) can be found here:

• http://www.vogella.com/tutorials/Checkstyle/article.html

The Long Story

... made short by Wikipedia: https://en.wikipedia.org/wiki/Checkstyle

Some modules are readily available, saving you lots of time configuring the tool:

"Checkstyle defines a set of available modules, each of which provides rules checking with a configurable level of strictness (mandatory, optional...). Each rule can raise notifications, warnings, and errors. For example, checkstyle can examine:

1. Javadoc comments for classes, attributes and methods;
2. Naming conventions of attributes and methods;
3. Limit of the number of function parameters, line lengths;
4. Presence of mandatory headers;
5. The use of packets imports, of classes, of scope modifiers and of instructions blocks;
6. The spaces between some characters;
7. The good practices of class construction;
8. Duplicated code sections;
9. Multiple complexity measurements, among which expressions." (Source: Wikipedia)

Similar tools

If you're into .Net, think FxCop: 

https://en.wikipedia.org/wiki/FxCop

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!

SW Construction: Let's do it like they do it on space? | NASA Coding Conventions

So I remembered that some (oldie but for sure goldie) coding conventions are freely available from NASA JPL, several languages available:
https://www.google.pt/webhp?sourceid=chrome-instant&ion=1&espv=2&ie=UTF-8#q=nasa%20jpl%20coding%20standards

FFR. But meanwhile you can start applying it (and doing "IT" like they do it on - i,e. for - space)

BOOK: Clean Code | Robert C. Martin

So, another good book on how to write good (clean) code to keep in mind is Robert C. Martin's "Clean Code: A Handbook of Agile Software Craftsmanship":

https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882

Quoting:
"Even bad code can function. But if code isn’t clean, it can bring a development organization to its knees. Every year, countless hours and significant resources are lost because of poorly written code. But it doesn’t have to be that way.

Noted software expert Robert C. Martin presents a revolutionary paradigm with Clean Code: A Handbook of Agile Software Craftsmanship . Martin has teamed up with his colleagues from Object Mentor to distill their best agile practice of cleaning code “on the fly” into a book that will instill within you the values of a software craftsman and make you a better programmer—but only if you work at it.

What kind of work will you be doing? You’ll be reading code—lots of code. And you will be challenged to think about what’s right about that code, and what’s wrong with it. More importantly, you will be challenged to reassess your professional values and your commitment to your craft.

Clean Code is divided into three parts. The first describes the principles, patterns, and practices of writing clean code. The second part consists of several case studies of increasing complexity. Each case study is an exercise in cleaning up code—of transforming a code base that has some problems into one that is sound and efficient. The third part is the payoff: a single chapter containing a list of heuristics and “smells” gathered while creating the case studies. The result is a knowledge base that describes the way we think when we write, read, and clean code.

Readers will come away from this book understanding
How to tell the difference between good and bad code
How to write good code and how to transform bad code into good code
How to create good names, good functions, good objects, and good classes
How to format code for maximum readability
How to implement complete error handling without obscuring code logic
How to unit test and practice test-driven development
This book is a must for any developer, software engineer, project manager, team lead, or systems analyst with an interest in producing better code."

Table of Contents 

Clean code

Meaningful names

Functions

Comments

Formatting

Objects and data structures

Error handling

Boundaries

Unit tests

Classes

Systems

Emergence

Concurrency

Successive refinement

JUnit internals

Refactoring serialdate

Smells and heuristics

Appendix A: Concurrency II

Appendix B: Org.jfree.date.serialdate

Appendix C: Cross references of heuristics

Epilogue.

Code Reviews and the "If it ain't broke, don't fix it" principle

"If it ain't broke, don't fix it." is credited to Bert Lance as the person who popularized it, when he was quoted saying it in the May 1977 issue of the magazine Nation's Business.The expression became widespread, and William Safire wrote that it "has become a source of inspiration to anti-activists." - Wikipedia

Sometimes this principle will be put in place while performing Code Reviews (CR is a verification measure that intends to spot software defects by reading the software source code, as early as possible in the software life cycle). This only means that the main reason you are reviewing the code is to spot defects, so optimizations, formatting issues are out of scope (even if they bother you, don't engage into unnecessary discussions with the author).

Unless, of course, they are part of the written coding conventions for the project (some projects will inherit whatever the company or the customer have). This means that indenting code at 2 spaces instead of 4 could be a defect if there is a coding convention for this team that requires this specific indentation.

Also sometimes, as input to a code review a check list (of different sizes ;) could be handed to you. And those check lists could cover more that spotting defects.

So this principle applies in principle for code reviews unless there is a good reason to break it (Software coding conventions, check lists that are input to each code review).

Got it?