stellar
Document coding conventions that are not covered by a plugin
We would like for most of our coding conventions to be enforced by plugins in our build chain. For things that cannot be covered by this, let's document our rules in a markdown file.
Here's an example of an outdated coding convention guide: https://github.com/stellar/product-conventions/blob/master/STYLEGUIDE.md
@CassioMG can you expand on what you think we should be doing for this task?
@JakeUrban did you mean to tag me or @piyalbasu ?
I personally like having code conventions like what this task is proposing, so we agree on a pattern while writing things which makes it easier to understand and maintain the code on the long run. After the team gets used to it I believe we end up spending less time figuring out what each line of code means.
I don't think it's something critical though, but would be a plus.
@piyalbasu mentioned during grooming that you wanted to establish come conventions, but if not we can close this ticket
I believe the code convention that we'd probably most benefit from is always using single object as function input, like it's explained on this other ts wallet sdk issue as it makes the code more scalable and automatically prevent bugs related to function inputs being out of order.
Another convention that I believe would be nice to have is try avoiding using nested ternaries as nested ternaries make the code harder to read. There is actually a lint rule for this: no-nested-ternary.
A third one that came to mind is try opting for early returns instead of "if else" blocks.
I think this:
if (a) {
// imagine a big chunk of code here
return;
}
// another big chunk of code here that is safe to ignore in case we early returned
// code path ends right here
Is much easier to rationale when compared to this:
if (a) {
// imagine a big chunk of code here
} else {
// another big chunk of code here that you'll need to scroll down and maybe read through to only then discover the code path is ending right after it
}
// code path ends right here
Also this:
if (a!) {
// early return if the condition is not met
return;
}
// imagine a big chunk of code here
// code path ends right here
Would be better than this:
if (a) {
// imagine a big chunk of code here
}
// code path ends right here
@piyalbasu @aristidesstaffieri @Brunonascdev @danilosilvackl curious about your thoughts on this
I agree with your suggestions there @CassioMG, they really do make the code looks cleaner. But looking at what @piyalbasu wrote on the first comment of this issue, I think we can also document some other patterns that make it easier for newcomers and for outsiders to contribute/understand our code better as well.
one example would be naming conventions like this one, should we name all interfaces as IClassName or something else?
or for example some best practices, "avoid using magic string and magic numbers", "if its a one line code shared between multiple files, add it to the constants file", "if the code is used in multiple places, consider moving to a separate hook or helper file"
there is much more to consider when we think about writing a crudely speaking, beautiful code that we can also document and will improve code quality in general
