Saturday, October 22, 2005

Code Complete Review

I read Code Complete by Steve McConnell again this past week. This book is one of the few books I recommend for every programmer on my website. Anyone can read a book on how to code C++ in 21 days, but that doesn't make them a competent programer. After a few years of programing you will learn things from other programmers and from yourself. Not big things, but little things such as:

When working on a problem often times it helps to go to someone else and talk it out. You will probably find that all you need to do it talk out the problem, the other person doesn't even have to say anything.

or

Hard coding that 48 pixel size for every toolbar button isn't a good idea, using a global define is much better.

Your average computer book normally don't concentrate on these types of topics/tips, because they aren't important in teaching you PHP, C++ or how to design user interfaces. But they do make you more productive by making your code more easier to read, easier to maintain, and easier to debug. This book doesn't just teach you tips for writing code, but also dealing with schedules, managers, projects, and everything project related. I do not know of another book that contains the breadth of tips like Code Complete. Here are just a few of the types of tips that are contained in the book:
  • How to use parameters
  • How to name boolean variables
  • Different types of design
  • Enumerated Types, when to use them, and how
  • How to write defines (named constants) and why you should
  • Use variables as short of a time as possible and why
  • When to use a while loop over a for loop
  • When not to use break
  • Tips with boolean expressions
  • Benefits of structured programming
  • How to lay out and format your code (white space etc)
  • Keys to effective comments
  • Estimating schedules
  • Debugging, more then just printf()
  • Project integration strategies
  • Optimization strategies
Those who program in the open source world will find themselves exposed to many similar tips and tricks just by reading other peoples code. In fact this is one of my favorite parts about open source. As I read others code I often learn something new. Then when you submit patches they might be rejected not based upon correctness, but upon how the code is formatted, comments, or other bits that matter more in the long run.

I would recommend Code Complete to any programmer. Beginner programers will of course get more out of it and older programmers will find the book contains many good reminders and perhaps some tips they knew, but had never defined.

KApplication and other KDE4 work

Lots of exciting stuff is going on for KDE 4. Recently I have been hacking on KApplication. Over the years KApplication turned into a storage location for anything that couldn't find a home. A month or so ago I printed out KApplication and QApplication api docs for some weekend reading and planning. Taking it in small, mannagable blocks I have removed quite a lot from KApplication and even more can be done once Qt 4.1 is released. But what makes this really exciting is that as each patch got in, the interdependency in kdelibs was reduced. This will help us in the goal of separating the kde libraries. Yesterday, after a little work I was able to run a KDE application (trusty KTron) using QApplication. Work still has to be done, but we are on our way.

Doing some very unscientific tests you will be happy to hear that your average KDE application seems to drop 3MB in memory size just by porting to Qt4.

Also, for those interested in reading the commits to KDE's svn but don't want to sign up to the mailinglist here are two rss feeds that you can subscribe to.
Topic: Directory of change
Topic: First part of the commit messages

Tuesday, October 18, 2005

Why you want to write api docs

Writing code for the kde libraries is not like writing a class that goes in your KMyBigApp. Once it gets into kde's libraries it will have the following:
  • The structure of the class can't be changed much.

  • A lot of people will (try to) use your class.

  • A lot of people will read your documentation and curse at you if it makes no sense

  • A lot of people will read your code

  • Every stupid bug will be found such as calling foo() crashes the class every time or never returns the correct result.

  • The person hiring you for your next job might look at it. (actually these days it is pretty much guaranteed they will Google for some of your code).


What am I really saying? Writing documentation (and tests) for classes in kdelibs is very much about personal pride. It isn't just a class in your application, you know that people will look for documentation, use every function, and use it in a way that you never thought of. If you have no documentation then you will have people annoyed at you. If you don't write a test application that minimally calls every function the moment someone else does and breaks your class you will feel stupid. If you take the time to write some documentation and test application you are forced to think about your class and how it best fits into a larger application. Once you do this you will discover a few things to tweak in the structure to make it better. Writing documentation and tests for a class in a library isn't busy work that you don't have time for, it is professionalism.

And if you have no professionalism you can always fall back to: Those who submit new classes today to kdecore-devel with docs and tests get a big thank you (from me and others), and those that don't have docs get rejected, it is part of the kde policy.

Monday, October 03, 2005

Web based office suite

Over on slashdot there was an article about how an online office is _coming_ (insert ominous music). Quickly reading through the comments I am amazed at how few people get the value it could provide. I was chatting with some friends of mine about this a year or two ago.

Lets say I made an online editor, now my document editor is simple, damm simple, it only lets you edit the raw html for your document. Having word count and bold text isn't the value of an online editor, there are many other values
  • Backup is garenteed. Assuming the admin hosting the "application" isn't an idiot your documents will never be lost from your mistakes or your bad hardware. Already this is better then most companies today.

  • Revision control. Outside of development you don't code documents under revision control. Most users haven't a clue what it is. With the ability to store every change in a real revion control system on the backend you get all sorts of possibilities including:

  • Access anywhere. I don't know how many times I have been over at someones house and pulled up some vacation photos to clairify something because I have them online. If you have your documents online you will be likely to reference old ones in at random times. Can't do that today with them on home computer.

  • Clean merging when multiple people edit a file. I don't think you can do that in any mainstream text editor today. I am talking about the ability to merge files like we can do today with svn and code.

  • No pesky filesystem or filename to deal with. You simply save the document and search for it when you want to edit it. Users stress out about the name of their files anyway.

  • Instant publishing. When you are done you can mark it as global so that anyone on the outside can view your document. Imagine just browsing around on the internet checking out other peoples documents that they wrote. The key thing being that it
    would take no effort to "publish" the file. And if you have to fix something you just edit the document and it is done.

  • The ability to merge parts of other documents into yours and when those documents are updated so are yours (like a quote or paragraph).

  • Global searching. If your company has all their documents up on this repository then it will be very easy to find any document (say the spec written for a product from five years ago...), compare that with today...

  • If your company changes its name, or on a personal level you change the project name it will be easy to find all of the Documents that use the old name.

  • No more 50MB doc files. You can have a repository of accessory files. Call them clip art, call them vacation photos. You can create multiple documents that use the same 2MB images without having to make a copy of the image. You make a logo for a project and change it, update in one place and be done.

  • The ability to add media to everyones clip art in your family/company

  • Readers can leave comments on your documents. Think slashdot or messageboard style. This could be public or private, either way a valuable way for feedback.

  • LIVE status reports. The chief editor for the paper could just browse to a webpage that tells him the number of words of each of tomarrows articles to see which ones are done. And that is just the tip of the iceburg on reporting.

  • Your printer doesn't work? Just go over to your freinds and print it out on their computers web browser



Online document storing is coming. I could give a rats ass if it doesn't let me add footers or do a word count in version one, but if it starts adding the above colaberation abilities hoochy-mama I am going to put it on my server. Some will argue that we are already there. Wikipedia comes really close. A company could make a fat client with all the nice features for editing the files, but the key is that the files are stored on a remote server that is web accessable to enable all of the above.

Hell I am all excited about this I almost want to go code it myself.

Popular Posts