That is great when you can do it, but there are a lot of places (domain knowledge for instance) where documenting WHY this code exists is important I think. That and in general it feels like we should be documenting the "why" instead of the "what" if that makes sense.
It depends on the context. Most often I try to keep the explanation as close to the code as possible, so a docblock at the top of a method, or an inline comment block right next to some code that seems clear what it is doing, but maybe not the REASON for it being there.
This can help a lot later too, when it comes time to refactor. For example, you might have some code that is used to work around some odd bug in an API or something. That is a great place to comment about WHY it is there, and when you might be able to retire it. I do this a lot when I have to work around bugs in other systems I am integrating with but don't have code access to.
All that said, I do keep a pretty extensive evernote collection. This is most useful when hunting down weird bugs or issues, as you can quickly outline what the problem was and the steps you took while investigating and fixing.
These have BOTH saved my bacon numerous times, and I highly recommend getting in the habbit of doing both.
I stick with Evernote because it is synced everywhere, and can be quickly pulled up and saved. Though there is one caveat there: The latest version (10.x) is significantly worse than the 6.25.x line. They moved to an electron type app and lost all the global hotkeys and direct note linking and such.
I might take that one step further.
Good developers write their code and document it specifically for the "next guy".
So that they don't have to explain it in person.
And great developer produces code which is self-documented, so he spares time with "document the code" step.
That is great when you can do it, but there are a lot of places (domain knowledge for instance) where documenting WHY this code exists is important I think. That and in general it feels like we should be documenting the "why" instead of the "what" if that makes sense.
Agreed.
Thanks for this @beernutz . It is something I really struggle with and would like some guidance.
How do you this easily? Do you document via comments or using an external application (like Notion, Google Docs etc).
Will appreciate your insights.
It depends on the context. Most often I try to keep the explanation as close to the code as possible, so a docblock at the top of a method, or an inline comment block right next to some code that seems clear what it is doing, but maybe not the REASON for it being there.
This can help a lot later too, when it comes time to refactor. For example, you might have some code that is used to work around some odd bug in an API or something. That is a great place to comment about WHY it is there, and when you might be able to retire it. I do this a lot when I have to work around bugs in other systems I am integrating with but don't have code access to.
All that said, I do keep a pretty extensive evernote collection. This is most useful when hunting down weird bugs or issues, as you can quickly outline what the problem was and the steps you took while investigating and fixing.
These have BOTH saved my bacon numerous times, and I highly recommend getting in the habbit of doing both.
I stick with Evernote because it is synced everywhere, and can be quickly pulled up and saved. Though there is one caveat there: The latest version (10.x) is significantly worse than the 6.25.x line. They moved to an electron type app and lost all the global hotkeys and direct note linking and such.
@Ekanem, On Pull Requests!
Following this template here in our company(skore.io):
What?
Change something...
Why?
Because...
Link to the card/ticket.
I appreciate your detailed feedback