Does anyone keep a journal as they develop code? Something to keep track of ones thought process so that you understand what you were thinking when you come back to it? I know most people just use comments, but does anyone use something different?

Also, I don't mean this as a replacement to comments (all code should be commented), but more as a device to go more in depth so as to keep from writing a novel of comments?

I use git 😏. That is kind of like a journal

Ooooo watch out. Think people may disagree that all code should be commented 😅

@mrstebo Why is that? IMO, uncommented code just makes the life of the next guy who takes over development a whole lot harder.

The general argument is that the code should be "self documenting". If your code has a comment, then perhaps it is unclear what that bit of code should be doing.

Comments are only really required if the piece of code you are commenting is a "hack", or you are making the developer aware of an issue with some third party dependency

I use draw.io to make logical flowcharts. When it is ready you can start your journey and see your progress step by step. Great help in database table connection planning aswell.

@mrstebo I guess that makes sense. But lets say its not the code that is unclear, but the thought process behind it? What if the guy who came before discovered a particular reasoning behind why something should be done a certain way. Would that not justify a reason for commenting that section?

You'll see a lot of refactoring talks about making really small methods that do exactly what they say on the tin 😉. I would recommend watching some of Sandy Metz and Ben Orstien ruby talks. Was a real eye opener for me 😁

@mrstebo Thanks, i'll check those out (:

@castor-rg if there is something that really needs explaining it should probably have a wiki page. I think the are projects on Github that have a wiki specifically for anyone contributing to a project. So all the technical details and thought processes can be put in there

I haven't done this for nearly a year now due to the time pressure on my latest project. By I used to keep an "oldskool" journal (pen and paper) to write down things I learned on the go. Sometimes I print small snippets as examples and place them on the page with experience I wrote down.

It happens quite often that I remember something I did before, so I started writing it down. It actually helps me.

Mindmaps?

@castor-rg @mrstebo I think.commenting code and having a specification of your system is very important. Code should be self-documenting is a myth(IMHO). Atleast all the code I have wrote I've always thought which idiot wouldn't understand this simple explicit code, but coming back to it even after a month takes a bit of time to parse what's going on. Since then I've been paying more attention to documentation and specification, and honestly it has paid off.

Also might be interesting to you guys - check out literate programming.

@castor-rg Yes, I use OneNote to informally document the original purpose of a project, why no TRD nor spec was written, why management changed their mind, shortcuts taken to accommodate redesign, all emails related to project, and any configuration setup I had to go through to set up my dev environment.

I originally wanted a Wiki for each project, but Project Management saw no value in "documenting executables", so OneNote it is.

At work we all have logbooks, the company was started by engineers. They're all older, been out of uni 10+ years and usually migrated from engineering, I graduated a year ago from CS.

I find myself using a text editor as a scratch pad and comments in code to explain. Generally you shouldn't need long comments, the code should be self explanatory for people that understand the language. It's fine if you're pointing out jank in third party code, or latex/doxygen to explain what it does.

As much as anything I'd prefer to keep the code and explanation of it together.

We also have a docs folder that is used for diagrams, specs usually more formal.

I use OneNote more and more.