thinking

I often have trouble maintaining long-term direction in my work. I can’t remember exactly what I worked on three days ago; what I did three weeks ago is hazy at best. This makes it hard for me to keep the big picture in mind – how much time and effort I’ve really devoted to any particular project.

That’s why I’ve written a command-line program to keep track of what I’ve done. It’s called wj, which stands for work journal. It’s free and open source – installation details below.

wj helps you record and summarize what you do each day, week, month, and year. At the end of each year you get a one or two page pdf summary of everything you did, expressed in a clean week-by-week list of your accomplishments.

This is my personal replacement for software-based todo lists. I like short-term todo lists that are meant to be disposed, because they help me think carefully about what I want to do in the next several hours. If the todo list isn’t disposable, then the things I thought I wanted to do, but don’t really, just pile up undone and build useless stress.

So wj is not a todo list – it’s a done list. It’s a way to get feedback without a manager. If your work is lagging, you can see it quickly using wj. If you’re doing well, you can see that, too, and reward yourself.

Here’s a sample screen:

To use wj, just type ./wj.py from the command line. I have a symlink set up like this:

$ sudo ln -s /path/to/my/wj.py /usr/local/bin/wj

so I can just type wj anywhere to run it. wj also has a command-line interface so it can easily be used within bash scripts or anything else that can call command-line functions (so, virtually any modern programming language). Since it’s written in python, you can also import it as a python module and gain a deeper level of control over how you interact with wj – write your own interface to it, for example.

Features

wj records a snippet of text about what you did every day, week, month, and year you use it. This is text you must enter yourself, nothing magic. It keeps these snippets organized chronologically and by time scope (day/week/month/year). It can generate a pdf for each year you use it (technically, it generates a tex file that you can turn into a pdf by running pdflatex). I’ve designed the pdf to capture a detailed overview of an entire year in just two pages. This pdf includes every snippet at the year, month, and week level. Imagine using wj for 10 years, and having a nicely formatted 20-page notebook with everything you’ve done, down to the week, for the past decade. To me, this vision is very satisfying, and I see wj as a tool to help me achieve this.

For more specific details on how to use wj, type wj -h for the command line actions, or just run wj with no parameters to enter interactive mode (screenshot above).

wj also supports two calendar modes. Gregorian is the default mode that most people use. I use a different calendar system that I created called the 7date, which basically uses the day-of-the-year written in base 7. I could easily fill another blog post detailing the advantages of the 7date, but for now I’ll be brief and simply say that it’s a better system that is fully supported by wj. If you like the Gregorian dates you’re used to (things like Dec 10th 2025), then there’s no need to worry about the 7date at all – Gregorian is the default mode in wj.

Here’s a sample pdf for my year so far. The dates on that are 7date months and weeks, so they’ll just look like numbers to most people (sorry about that). wj didn’t exist at the beginning of the year, so my entries start later in the year.

Design principles

wj.py is the only file you need to run wj, along with python2.6 or later. I despise the complexities that often go along with installations and dependencies, so I put everything in this one file.

All the data is kept in the directory ~/.wj. If you want to backup your data, copy this directory somewhere. It will contain one file called config, which has some comments to assist you in editing it, and one file per year you’ve used wj, named after the year it depicts.

wj is open source under the Apache 2 license. It is free to use and redistribute, and will remain free forever. I would be happy to have code contributions that improve it within the vision. I would like to avoid new features. Mainly I would love to see it get a little easier to use, install, and look a little better – primarily in the pdf output.

Installation

The github project for wj is here:

https://github.com/tylerneylon/wj

If you want to download it, you can get it from here:

https://github.com/tylerneylon/wj/downloads

As I said above, you can run it directly by typing ./wj.py from the directory you downloaded it to, or you can create a symlink using the above command (the “sudo ln -s …” one), and then just type wj from anywhere.

Enjoy!

I just finished reading the book on programming in C, which is appropriately called The C Programming Language, by Brian Kernighan and Dennis Ritchie. It’s nicknamed “K&R” after the authors. Dennis Ritchie invented C and was a major designer of unix. Brian Kernighan wrote cron and is the k in awk, among other awesome things.

The thing is, I’ve known C for a long-ass time – since before Microsoft released their first C++ compiler, which is when I learned C++ (from the book that came with the MSVC 1.0 box). So why did I bother to read K&R now?

First, it’s an inspiringly well-written book. There are a very small number of books that start from the basics and lead you all the way through to the advanced stuff, without skimping on the details, and this is one of them (another is Calculus by Michael Spivak, or The TeXbook by Donald Knuth). I love books like that. They are both fun and efficient to read – beautiful. Secondly, the more I program, the more I appreciate deep mastery of a language. And finally, I am in the midst of designing a new programming language for fun.

Interesting stuff from K&R

I thought about turning this into an essay, but it’s more fun to read the way I took the notes: as a random jumble of interesting tidbits that caught my eye as a veteran C programmer reading K&R for the first time. If you’re in the same position – you know C but haven’t read K&R – consider this a summary just for you!

• The point of a struct tag (as in struct tagname { int i; float f; };) is to effectively define a new type called struct tagname. I’ve always used typedef’s, so I never really understood the point of the tags before.
• The authors like 4-space indents (I like 2, and Linus Torvalds likes 8).
• The authors are ok with brace-free one-line code blocks, such as a single line after an if statement. Every style guideline I’ve ever read (and yes, I’ve read a few) has forbidden this, so it’s interesting.
• They like assignment and/or increments within conditional expressions (as in the line if ((fp = fopen(*++argv, "r")) == NULL) { on page 162.) I prefer to have about one primary verb per line of code.
• They sometimes declare function prototypes within function definitions. I didn’t even know that was legal.
• They sometimes declare both variables and function prototypes in the same comma-delimited list.
• The names for argc and argv come from “argument count” and “argument vector”.
• The type void was originally not in the language.
• They didn’t seem to feel very strongly against global variables. I’ve read in many places that global variables are basically forbidden, though I personally think they are not so bad if you can use them without polluting the global namespace, treating them as essentially local to a file or very small set of files.
• There is a rationale behind the syntax for all pointer declarations (including for function pointers): they are designed so that if you replaced *myVar with just myVar, you’d get a declaration for the pointed-to object. And they chose this since, at usage time, when you dereference a pointer, you are talking about *myVar, so there is some consistency there (I wish someone had told me this idea a long time ago – it makes a lot more sense now!)
• The authors sound as if they wished malloc could have returned a more specific type based on the input, which makes sense. I like that they care more about design honesty than salesmanship.
• You can make bit-fields with a struct! As in, you can declare struct fields to be a certain number of bits in size. I didn’t know that. I guess most people prefer bit-wise operators, though, because I don’t think I’ve ever seen that used.
• In printf, you can provide variables for field-width specifiers; for example printf("%*s %*.*f", 8, "hi", 5, 2, 3.14159) will print out "      hi 3.14".
• The authors don’t mention buffer overflows when talking about things like sprintf, strcpy, or memcpy. Ruh-roh, be careful newbie coders!
• File-handling functions like fputs or fprintf accept the FILE pointer in different positions – it would be easier to use if it were always the first parameter. They also include a sample of what’s behind a FILE pointer, which is somehow very satisfying to find out (it always felt like a sort of condescending mystery to me).
• I still don’t know what the beginning c in “calloc” stands for. (Some people say “clear” but I don’t see anything definitive. See here.)
• In example 8.6, they return a pointer to a static variable, which some folks consider to be bad practice.
• Technically, you’re not allowed to compare pointers unless they’re within the same array (or one past the end). I didn’t know it was so restrictive. I also noticed their sample implementation of malloc/free breaks this rule.
• They really like one or two-letter variable names. Check out the implementation of free on page 188. I like slightly more descriptive names, sort of in the python culture (as opposed to ass-long names, as in the java culture).
• There is some insane stuff going on in setjmp.h. I had no idea.
• Here’s an example of a declaration that’s fairly tricky to parse: void (*signal(int sig, void (*handler)(int)))(int) What? It’s a function that takes an int and a function pointer as inputs, and returns a function pointer as well.
• There used to be a keyword called entry but it was dropped from the language. I wonder what it might have done (they don’t say).
• Incremental assignment operators like += used to be written in the other order (and allow spaces between them!) like x =+ 1, but that was changed due to the ambiguity of something like x=-2.

Good stuff.

A new language

I don’t have much to show yet for the new language. The primary goal of the language is to be faster than C but still allow for very nice code, even while working with large-scale programs. I have some specific ideas for the speed in mind.

Other features I’m interested in:

• No classes; instead use scopes and interfaces together. A scope is like a struct in C, but can be smart about inheritance-like behavior, and an interface is like a pure virtual class in C++ or an interface in java.
• Built to give the coder maximal control, lisp-style.
• Post-compile optimization. Nuff said.