Programmer’s Notebook

In mid 90s I read an article about keeping a programmer’s journal. I don’t know where the article went, but recall sharing it with a couple of my friends. I knew it had something to do with the original wiki. I finally found it. It was an entry in one of my 2001 posts in a yahoo group. I don’t think it is the original, but this one is good enough to share.

I am trying to get a young project team to keep a learning log and project log. But I need to tell them how and why.  This page does a good job. But I don’t want to lose it again. So I put it everywhere I can think of (lots of redundancy). Here is a copy.

  • Start slowly; some log is better than no log. (AnyXisBetterThanNone)
  • Don’t postpone writing something down. Somebody else will come along, and you’ll forget your bright idea.
  • Put a date on every entry.
  • Number the pages so that you can easily reference them.
  • Use a consistent format so that you can easily go back and find something.
  • Use a horizontal separator line and a project name to separate individual subjects (e.g., music, theorem proving, or language research).
  • Use secondary headings that include the date and the subject (for example: “980425, Ideas on extending Java with laziness”).
  • Different kinds of entries, each with a special symbol in the margin: remarks, questions, definitions, to do items, MetaRemarks.
  • After every entry, leave at least a single empty line. This can be used for last-minute additions, the answer to a question, or a forward reference to more thoughts on the same subject.
  • Make it readable for yourself and others.
  • Log meetings with dates, attendees, topics and results.
  • Keep a separate ToDoList, or put it in a special place. Do not scatter ToDoItems? throughout your notebook.
  • LetYourLogsBecomeYourPlans

What are the current tools to keep a journal.

  1. Google Notebook
  2. Twitter – a couple of sentences on the thoughts as they occur with a special marker
  3. A wiki (which is what we are using now, with private spaces for each member of the project team)
  4. Your blog (if you want to write a lot more)

1 and 4 may work even for private info that you may not want to share publicly. What kind of items can you log? At the risk of repeating some from the list above, here is mine:

  1. Questions
  2. Resources
  3. How-tos
  4. Problems and How I solved them
  5. Idioms I learned (or used)
  6. Things to Research (like Questions)
  7. Why did I/we make a certain decision? What were the options?
  8. what did we learn – LearnLog
  9. List of things to do – TodoList
  10. Open Issues – Things to think about (no immediate action known)
  11. Ideas – IdeaLog

If there is one thing to remember, it is  “Start slowly; some log is better than no log”.

More resources:

LogBook

Self Improvement Patterns – Slightly related but fun to read

Golden Rule of Documenting Software Design

In the Next Programming Skill You Should Learn, Scott Hackett talks about the ability to communicate well, especially in writing. I totally agree. The post is certainly worth a read.

An unexpected bonus in this post is Scott’s tips on the golden rule of documenting software design.

The golden rule of documenting software design

Try to document whatever you are working on. It doesn’t have to be the worlds most perfect UML and you don’t need an expensive tool to do it. In fact, Wordpad and Paint are sufficient, and don’t tell me you don’t have those. Write in a way that best expresses your intent and your thought process in coming to the design decisions you did. I have a golden rule of documenting software design:

Describe your design to others as you would have others describe their design to you.

When you spend the time to do this, you’ll find that many benefits will follow. You’ll get feedback from others that may have tried to solve a similar problem and have insight you may not have thought of. You’ll leave a clear trail to follow for those that work on the code after you. Most importantly, you’ll shed light on your work, which everyone who depends on your work will appreciate. Even if no one else reads what you write, you’ll still have worked through problems in your head that can only lead to better design in the long run. There is no downside to documenting your designs.

One of the experiments I am conducting with a set of interns is to make them write a LearnLog and ProjectLog – just a few bullets or short sentences. We do this in a wiki so that every one in the project has access to it.  It is also one of the easiest and most effective ways to communicate asynchronously with the team.

In the Project Log, they are supposed to write the following:

  • Design decisions
  • Decision to use libraries/tools and why
  • Problem areas and stumbling blocks and how they solved it
  • A list of links to the resources they used

It is still an uphill battle but we are getting better gradually.

Math: Developing a Mindset

You keep hearing about Mathematical thinking. What is it? How do you develop a Mindset for Math?

Khalid has a nice post on How to Develop the Math Mindset.

Math uses made-up rules to create models and derive relationships. When learning, I ask:

  • What relationship does this model represent?
  • What real-world items share this relationship?
  • Does that relationship make sense to me?

I will add a couple of more:

  • How does one develop a mind-set for thinking beyond mere numbers, formulas and low level concepts.
  • How can we take these insights that come out of that mindset and apply to real problems

One of the slides I used to have on my “Thinking About Thinking” talks was to ask the audience (mostly CS students) to do a few of the following multiplications, mentally.

19 X 21

25 X 15

Very few actually find the simple algebraic patterns, till you point them out.

That brings us to one more insight (not my own):

  • A lot of problems can be solved by looking for patterns and applying some existing knowledge

The more mental models we build, the easier it is to apply them.

Simple Innovations: No Printer? No Problem!

I got this email as a Rapid Rewards member from Southwest Airlines today. It made me happy.

If you do not use Southwest, some background is in order. There are no seat assignments in Southwest Airlines. You take seats on a first-come-first served, basis. I felt that it was like a bus and never liked it much. Then they changed it a bit. You can check in early (24 hours  from home, on the internet and you will be assigned a boarding group – A, B or C. A group boards first, B next etc.  However, you needed a printer to check in and print your ticket, not very convenient when you are traveling.

No printer? No problem! Wireless Checkin is available at mobile.southwest.com! Simply log on to mobile.southwest.com via your web-enabled mobile device. Next, enter a valid confirmation number and the first and last name of one of the passengers listed in the reservation.

At the airport, visit any E-Ticket Check-In kiosk and reprint your boarding pass. The system will recognize that you’ve already checked in for your flight and will issue your boarding pass in the same boarding group that was indicated on the Checkin Confirmation screen from mobile.southwest.com.

Vigorous Writing is Concise

Vigorous Writing is Concise

I borrowed this phrase from Jon Bentley, who in turn was quoting William Strunk Jr.’s observation in Elements of Style. Jon says that this is true in both English and Programming.

In this chapter titled The Most Beautiful Code I never wrote, from the book Beautiful Code, Jon shows how you can do more and more with less and less.  He takes a quicksort program in C and through a series of steps, makes it smaller and better.

Yes. Vigorous writing is concise. It is a skill I am still working on.

Little Innovations: Math Lab in Your Cell Phone

From ZDNet’s Emerging Technology Trends

Israeli scientists have decided to put a math lab in your pocket. They developed a library of math modules which can be installed on almost cell phones available today. So you’ll be able to see graphs or solve equations on your phone while on a train or a bus ride. You’ll also be able to send graphs or formulas by SMS to other students — and to send the results of your exercises to your teacher.

This may just be the beginning. With cameras, ability to play flash, SMS and GPRS, these may become the new devices for augmenting learning.

Link As a Unit of Data

From Danny’s Evolving the Link:

Critics also pointed to the limitations of links that pointed in only one direction and were untyped. The Web’s success has to a large extent overridden these criticisms without really proving them wrong. Ironically, it now seems that many of the early criticisms weren’t exactly incorrect per se, but merely shortsighted.

The W3C’s Semantic Web Education and Outreach group recently agreed to support a community project called Linking Open Data on the Semantic Web. The project’s goal is to make various open data sources available on the Web as RDF and to set RDF links between data items from different data sources. Groups in the field made progress before the community project even began. Examples include the dbpedia.org project and the D2R Server publishing the DBLP bibliography.

The Web’s utility does depend on its level of deployment—the network effect—and it’s doing rather well there. But it would be disappointing if, after all this time, the Web was only just catching up technically with its predecessors. Virtually all the hypertext features said to be lacking from the Web have been formalized within various specifications. Conceptually, the key is viewing the link as a unit of data. If this view is overlaid on the current Web, then not only are the shortfalls the critics describe illusory, but there’s still a huge amount of untapped potential in the Web even in its current “simplistic” architecture. We’re entering interesting times.

My first introduction to Hypertext was through a special issue of BYTE magazine. I recall reading every article on that issue with excitement of the potential of a link. Then I met Doug. I was amazed at how much his Augment did with links.

I am glad to read this article from Danny for it brings back all those linked memories.

Three Steps to Efficieny

I was watching the video of Seven Habits of Highly Effective Text Editing. I am sucker for anything titled Seven Habits.  I use Vim (Vi improved). Vi was the first editor I started with on Unix and since there were DOS versions available, kept using it. So when I saw a session on Vim on Google video, I decided to watch.

Here is Bram Moolenaar’s mantra

  1. Detect Inefficiency
  2. Find a quicker way
  3. Make it a habit

I think this applies to programming as well and probably many other areas.

Joel “Software – A Game of Inches”

From Joel’s Game of Inches

Commercial software—the kind you sell to other people—is a game of inches.

Every day you make a tiny bit of progress. You make one thing just a smidgen better. You make the alarm clock default to 7:00am instead of 12:00 midnight. A tiny improvement that will barely benefit anyone. One inch.

There are thousands and tens of thousands of these tiny things.

It takes a mindset of constant criticism to find them. You have to reshape your mind until you’re finding fault with everything.

And as you fix more and more of these little details, as you polish and shape and shine and craft the little corners of your product, something magical happens. The inches add up to feet, the feet add up to yards, and the yards add up to miles. And you ship a truly great product.