Provide a company’s programmer’s guide

While working at REDACTED, I reported the following issue.

Create, maintain, and recommend the usage of a company’s programmer’s guide. It would be better suited by a Q&A (question and answer) website, with syntax colored snippets, with comments, with votes, with reputation, very much like an on the premises StackExchange website.

It would answer questions like: How do we manage money data type?

This is a real question I had to ask at some time, but both Front end and Back end folks couldn’t give me a definite answer.

In Back end they use something called BigMoney, a class with lots of attributes, and they document it like so in the Swagger website, but then the endpoints exchange a string with some decimal number and some currency in it, while at other times, they exchange a POJO with an amount string and and a currency string.

Even if I was surprised by the incoherences here, what suprised me more was that nobody was able to give me a definite answer. With a company’s programmer’s guide there wouldn’t be any doubts.

Of course, not being able to answer such a question meant that they also couldn’t answer related ones, like How do we manage precision in money computations?How do we manage money localization?

Some days after asking my question, and making them notice that I considered it unacceptable for a banking software company to not know the answer, my Front end colleagues hacked up a “solution” into an old input component.

The new money functionality had been made available using a generic text input component, with a special amount type, with a required amount validation, and with a couple of additional ugly quirks:

when you want to set a money value, like USD 12.34, you have to manually erase the currency in it before;

when you want to get a money value, like USD 12.34, you have to call the special getAmount instead of the usual getValue.

That would be juniorship showcase if code review had fixed it. Instead it got into the code of the UI Components module. I mean, juniors have some right to make certain mistakes, but seniors?

It would recommend basic best practices like:

  • avoid completely useless comments like this:
// form
form: Form;
  • avoid useless comments:
// search form
form: Form;

using self-documenting code:

searchForm: Form;
  • add useful comments, when your self-documentation doesn’t cut it
// We put searchForm here because we want to offer
// our users alternatives and upsells that take into
// account all their previous choices

Leave a Reply

Your email address will not be published.

This site uses Akismet to reduce spam. Learn how your comment data is processed.