From 06067ea544521280002eae73092f1ba410ccdd93 Mon Sep 17 00:00:00 2001 From: Julio Biason Date: Tue, 16 Jul 2019 12:31:06 -0300 Subject: [PATCH] New chapter: auto-formatters --- content/books/things-i-learnt/_index.md | 1 + .../things-i-learnt/code-formatters/index.md | 49 +++++++++++++++++++ .../code-reviews-style/index.md | 2 +- 3 files changed, 51 insertions(+), 1 deletion(-) create mode 100644 content/books/things-i-learnt/code-formatters/index.md diff --git a/content/books/things-i-learnt/_index.md b/content/books/things-i-learnt/_index.md index a9dc0b5..e16cc49 100644 --- a/content/books/things-i-learnt/_index.md +++ b/content/books/things-i-learnt/_index.md @@ -64,3 +64,4 @@ template = "section-contentless.html" * ["Right Tool For The Job" Is Just To Push An Agenda](right-tool-agenda) * [The Right Tool Is More Obvious Than You Think](right-tool-obvious) * [Code Reviews Are Not For Style](code-reviews-style) + * [Code Formatting Tools Are Ok, But No Silver Bullet](code-formatters) diff --git a/content/books/things-i-learnt/code-formatters/index.md b/content/books/things-i-learnt/code-formatters/index.md new file mode 100644 index 0000000..75c54b5 --- /dev/null +++ b/content/books/things-i-learnt/code-formatters/index.md @@ -0,0 +1,49 @@ ++++ +title = "Things I Learnt The Hard Way - Code Formatting Tools Are Ok, But No Silver Bullet" +date = 2019-07-16 + +[taxonomies] +tags = ["en-au", "books", "things i learnt", "code formatting", "code style"] ++++ + +One thing a team may decide to fix the continuous flux of code style comments +in a code review is to use a code formatting tool to auto-format the code. +That's ok, but they should never rely on it. + + + +Now yeah, that kinda solves the problem, but there is one small problem: +we, humans, are not as flexible to read code as computers are; what is +readable by a computer may not be readable by a human. Surely they try to +create some heuristics on what is good for human reading, but that doesn't mean +it gets right. + +Also, unless you start from scratch to use the auto-formatting tool or do a +change in all files in one single go, you should never assume it will do a +good job. + +I've seen tools like this implemented in a commit hook, in a way that the tool +would reformat the code just before adding it to the repository. The biggest +problem is that, in that team, we didn't run the auto-formatting tool in the +whole project before hand, and we also added a coverage tool (that checked the +coverage on the changed parts of the file) without every running the coverage +tool on everything. The result is that, suddenly, a lot of commits got refused +because the auto-formatting tool was changing lines that the developer didn't +change (it changed old code) and suddenly the coverage tool noted the missed +tests and decided it was no good. + +So good, punctual changes were suddenly being blocked 'cause instead of doing +the whole thing in a single shot, people decided it was a good idea to let the +code evolve till everything fixed itself. + +On top of that, some people who were neither in the mood to actually add the +tests or worried about style found a way to do the commits _without running +the hook_, so they basically skipped the whole "let's improve our code" and +let fuck all. + +So, it's ok if you run the auto-formatting tool for yourself, but you need to +have the maturity and responsibility to watch yourself and be willing to fix +and take responsibility for other people's code when the formatter changes +their code. + +{{ chapters(prev_chapter_link="/books/things-i-learnt/code-review-styles", prev_chapter_title="Code Reviews Are Not For Style") }} diff --git a/content/books/things-i-learnt/code-reviews-style/index.md b/content/books/things-i-learnt/code-reviews-style/index.md index b734927..6ed78a1 100644 --- a/content/books/things-i-learnt/code-reviews-style/index.md +++ b/content/books/things-i-learnt/code-reviews-style/index.md @@ -29,4 +29,4 @@ On the other hand, if you find something weird in the code which is something you want the author to recheck, _then_ you're free to comment that "it would be good" if they fix the style. But that's it. -{{ chapters(prev_chapter_link="/books/things-i-learnt/right-tool-obvious", prev_chapter_title="The Right Tool Is More Obvious Than You Think") }} +{{ chapters(prev_chapter_link="/books/things-i-learnt/right-tool-obvious", prev_chapter_title="The Right Tool Is More Obvious Than You Think", next_chapter_link="/books/things-i-learnt/right-tool-obvious", next_chapter_title="The Right Tool Is More Obvious Than You Think") }}