Contribution guidelines need documenting

[KirbyKatcher]

As a galasa contributor, I want to know what coding standards and best practices are used, so that I can contribute to the same level of standard as other contributors.

Tasks

• [ ] The team should independently review the following guide and comment below any items found which they disagree with
  • [ ] Java
  • [ ] Shell Scirpts
  • [ ] GoLang
  • [ ] TypeScript
    • [ ] Move https://github.com/galasa-dev/automation/blob/main/docs/how-to-contribute.md to the galasa.dev repo

[KirbyKatcher]

Suggestion for: Instantiating a Gson object

import dev.galasa.framework.spi.utils.GalasaGson;

...

public GalasaGson gson = new GalasaGson();

[KirbyKatcher]

Suggestion for: Indent spacing. The guidelines in the docs above all mention a 2 space indent. I think it is more clear to identify indents using a 4 space indent and would like to suggest we use that instead in all our code.

[techcobweb]

Javadoc comments not always required, even on public methods, if it's obvious what they are doing and to what.

Votes for this please ?

[techcobweb]

Methods should have one return statement. It should always be at the end of the method.

This applies to Java and Golang.

[techcobweb]

For java code, we should agree on a checkstyle file, and then start using that in all projects.

At no point should anyone abritrarily re-format all the code in a file (manually or with a tool). This means we loose track of any blame data that git holds... which can be useful.

@Mark-J-Lawrence has a suggested check-style file. (where is it Mark?)

[Mark-J-Lawrence]

I'm introducing a checkstyle file within the SDV Manager PR currently open: https://github.com/galasa-dev/managers/pull/940/files#diff-35672840481769694ece09fc2f30d4b6dff8e5cd3cf72796a6bd69cfdd88ef4e

(along with PMD, & Spotbugs static analysis, which I highly recommend)

[techcobweb]

• Error messages:
  • Relate to problem from the users' viewpoint as they read the message. Assuming they don't know the internals of the code. Tell them what could cause it and how to resolve it if possible.
  • Don't say 'Please'. Direct them explicitly. There is no need to say please.

[techcobweb]

• Javadoc should not contain @auth tags. We don't need to see developers' names in the javadoc output.