Rather than rewriting the purpose of function, the comment can be detail the reader need to aware of, or consequence of some type of request.
Here a better comment example.
By writing this comment, the reader doesn’t need to guess what’ll be the inside of JWT and can just directly read the comment.
But remember that for every line of comment you write, you’ll double the work required when you change the related code.
So ensure the comment is important enough to double the required work.
FormattingWhatever code style you choose, you need to stick to it and be consistent.
In our code base, to ensure the code style is consistent we use linter, specifically pylint to ensure we comply to PEP8 convention with some extra addition such as pylint-django and pylint-quotes.
Some may argue that we are extreme, but the code should follow exactly the convention, else the pipeline will be failed.
Failed pipeline :(Error HandlingUse exception rather than error codes.
Rather than this.
status = handle(request)if status == Status.
BAD_FORMAT: // do somethingBetter do this.
try: handle(request)except BadFormatException: // do somethingIf error codes used, we need to remember that we should handle that error and the code actually still flowing.
If, by chance, we actually forget to handle that, the code will continuing whatever the state it has until it actually broken somewhere or even worse it lay hidden as bug waiting to be exposed.
By throwing exception, you MUST handle the exception, else the code will stopped and nothing will be done.
Some little extra, you can add context to exception that you raised such as raise BadFormatException("login_id is not valid").
Unit TestingAs our time using Agile development methodology with Test-Driven Development (TDD), unit testing is a must in our code base.
But, here we will not discuss TDD principles or what not, instead we will discuss clean test.
Why bother keeping the test clean?.Remember that we need to change the tests as the production code evolve.
Keeping them clean is what will keep them useful and not a pain in the head.
So, what make test a clean test?.Quoting from the “Clean Code” book, there are three things, readability, readability, readability.
Test should be clear what is the given situation, what it will test, and what is the expected result.
Simpler, concise, and more expressive test will create more readable test.
Consider these code.
It’s not obvious what the test about, what will be tested.
The only thing that can be sure is the test expected to raise exception.
We need to be more expressive regarding test, especially the method name, don’t be afraid to spend more characters for test method name.
Now, the test is clearer.
The thing will be tested is those consecutive dots ‘.
’ in email address should be invalid.
Another thing to nice is for each method, only one assert should be exist.
Consider this test.
We maybe tempted to add one extra assertion to assert our post request is success i.
e.
has status code equal to 200.
But, that’s not required because it’s not what we test in this method and there are already test for that.
So keep the assertion exactly once.
References:Martin, Robert C.
Clean code: a handbook of agile software craftsmanship.
Pearson Education, 2009.
.. More details