Code docs that make sense - part II

Code docs that make sense - part II

1st part of this post can be found here. Document your API - Swagger Ok, doctest was for Elixir & Python. Many other languages / platforms have similar mechanisms at the various stage of maturity, but things get even better once you focus on documentation of your public API, especially if you're using open standards - like RESTful services or WS. In such a case, you've plenty of solutions to choose from. One of them is swagger.io. What's Swagger? If I had to invent a one-liner for it, I'd say that ... Swagger is an API specification "guardian" ;) You…

Read More

Code docs that make sense - part I

Code docs that make sense - part I

I've written many post concerning writing code this way or another. Same applies to writing tests - all kind of tests you can possibly imagine. But there's one kind of software development process output I've been notoriously avoiding: documentation. This topics is bit touchy - we all know the most popular statements / opinions regarding documentation these days: Clean code doesn't need documentation (AKA self-explanatory code) Interface(s) should serve as the formal specification & ... ... tests as its representative use cases (TDD/ATDD/BDD for different levels of abstraction) Every one of you have also heard about typical flaws of hand-written,…

Read More