Day 3: Keep a Programming Diary
Hi, this is the third part of a series of posts on 30 tips to becoming a better developer. If you would like to keep up to date with the topics that I am covering, just check the main post.
One of the things that make software developers different from other professionals is that they work with a very flexible material: programming code instead of iron or cement. However, given this big difference, some developers forget that beyond anything else they still are professionals. They fail on some basic tasks that everyone else has already figured out.
One of the things that most of us fail is on keeping proper records of our accomplishments. Some developers rely exclusively on tools such as source control and bug management software to define their tasks and record accomplishments. I think this is not enough.
Keeping a programming diary is a good practice that can not only become a learning tool, but also avoid a lot of trouble in the future.
What is a Programming Diary?
A programming diary is not a place to register your emotions and particular stream of thoughs. Leave this to your personal diary, if you keep one. A programming diary is more similar to a dayly recording of facts, decisions, questions, and conversations. It works just as a repository of information that is not structured enough to keep on the official design documents for your project. For example, here are some things that you would like to record in your programming diary:
- Important discussions about the project with your boss and co-workers;
- Changes on decisions about design;
- Things that went wrong;
- Ideas for improvement;
- Area of the code that are dangerous, or difficult to understand.
Keep it Online
One thing that we learned about information in the last few years is that it becomes more useful when more people have access. That is why your programming diary needs to be made available to the whole team, as the other resources, such a bug tracking database, are.
Think of this as an internal blog that contains information that should not be shared to the general public. In this digital diary you can keep the information flowing between you and the members of the group.
Some groups, like the company where I work, use a wiki for sharing this kind of information. I think this is a great resource, but having a personal diary for each developer is even more useful. The reason is that it makes each one to take personal responsability for the information that is shared. Wikis are nice, but there is always one person or another that takes control of the conversation (even if they are doing this nicely). With personal diaries, each one is responsible for the information they are sharing.
Conclusion
Many people use these ideas in one way or another, but I have seen no consistency in their use. Having a development diary is such a useful thing, however, that I recommend everyone to try it for a while. Understanding your own problems and decisions can make you learn more about where you need to improve. Ultimately, this is a discipline that can make you a better developer.
Further Reading
- The Pragmatic Programmer is a seminal book, that provides advice on this and related issues. This books is not from the pre-blog era, but still have useful guidelines that I recommend.
Go to the next post of the series:
Similar Posts:
About the Author
Carlos Oliveira holds a PhD in Systems Engineering and Optimization from University of Florida. He works as a software engineer, with more than 10 years of experience in developing high performance, commercial and scientific applications in C++, Java, and Objective-C. His most Recent Book is Practical C++ Financial Programming.
This should more be considered a “lab notebook”, which I think more precisely defines the objectives you’re trying to capture. I’ve done this for a while, and it is immensely helpful! :)
By Phillip on May 30, 2009
@Phillip: Thanks for comment. Yes, lab notebook is a great description. However, most people that are not from science wouldn’t know what this means.
By coliveira on Jun 4, 2009
Interesting!
A diary or a personal journal is your most intimate confidante. You can confidently share your secrets with it knowing that your personal diary will not talk to someone. So you should be very careful about your personal dairy. Leather is one of the most versatile materials that finds application in many areas. I would suggest to maintain a leather dairy instead of any normal dairy.
By Leather Diaries on Jul 31, 2009
Interesting idea and what I was following from few years. Thanks for the tip and I am happy that I am practicing good tips (PSP – Personal Software Practice ? ). The diary not only cite your day to day work, it should also document new thoughts left to subconscious mind, any algorithms, data structures practiced, etc. A blog (digital diary) would really help very well. The classical book
The Practice of Programming by Kernighan and Pike also worth mentioning here.
By A Geek on May 3, 2011
Thanks for the book suggestion, this is really one of the best.
By coliveira on May 4, 2011
I call it a .plan file
By Wanda on Jun 13, 2011
A smart move is to set up say a wordpress site, keep it in maintenance mode so nobody can read it, and disable comments for unregistered members. Then login to write your programmers diary there. Remember the password, and when you’re home or whenever you’re away from home, then you have instant access to your programmers diary. If there is an internet connection.
By Johan Brodd on Jan 5, 2012