Categories: Linux, Software Development

PHPUnit Essentials Book Review

PHPUnit Essentials would have come in handy while on a recent contracting gig and on all the other PHP projects I’ve worked on. The book is published by Packt Publishing, the last book I bought from them was on AngularJS and it was a great guide whereas as the O’Reilly book on AngularJS was outdated.

Overall the book was a good read and it’s worth getting as both a guide and a reference.
Continue reading “PHPUnit Essentials Book Review”

Categories: Linux, Software Development

First code patch submission in a long time…

UPDATE: It got in, the patch was reviewed, updated and added to the main code base. The developer even added my name to the credits!

I submitted an issue to the Django Rest Framework project. There was a bit of a problem with the documentation’s example not reflecting the code. The oft-repeated “the docs are never updated with the code” line that other programmers like so much ran through my head.

I think the way I presented the issue was solid…providing enough detail about what I was trying to do, the code that failed, the error message that was trigged, the version of the framework I’m using, and pointing the area of the code base that potentially caused my issue: https://github.com/tomchristie/django-rest-framework/issues/955

To remedy this situation, I forked the repository, created a new branch, made the fix, and created a pull request: https://github.com/tomchristie/django-rest-framework/pull/956

Documentation is important, especially when a project has over 1000 users. Updating it should be seen the same way as fixing code or adding new features, it shouldn’t be seen as a chore. As I quoted in a previous post, “some text is better than no text”.

The author of Django Rest Framework, Tom Christie, was super quick to respond. I got a response to the issue within a few hours. The frequency of releases isn’t too bad either, it feels regular and I would definitely continue using the project over tastypie.

I haven’t submitted a patch to any project in a long time, I’ve only reported a few issues and it will be awesome if this patch is accepted.

Generating a Culture of Code Documentation

Generating a Culture of Code Documentation

This is from a presentation given at the Write the Docs conference,

Cutter’s experience is that SMEs fall into three categories in roughly equal proportion: eager to help, willing to help (with guidance in the form of templates and direction), and curmudgeons.

…You as a writer have knowledge that engineers need to help them write docs effectively, and when you share that knowledge you help them write more docs. Hold doc office hours where you’re available to help them with docs. Because some text is better than no text.

Curmudgeons will say “but code documents itself!” Cutter calls “bull”; code only tells what it does, not its intent. [NB: Intent is worthless if the code’s action doesn’t match it.] Even if you know what you wrote immediately after you wrote it, six months later you’ll have moved on and that’s when the documentation becomes critical.

Categories: Linux, Software Development

Python Exceptions

http://www.jeffknupp.com/blog/2013/02/06/write-cleaner-python-use-exceptions/

Many programmers have had it drilled into their head that exceptions, in any language, should only be used in truly exceptional cases. They’re wrong. The Python community’s approach to exceptions leads to cleaner code that’s easier to read. And that’s without the monstrous hit to performance commonly associated with exceptions in other languages.

There’s a nice point made about exceptions vs error codes on the c2 wiki:

If you don’t explicitly handle an exception, Something Bad Happens, and that is a Good Thing. Consider the consumer and producer of some facility – in the simplest case, one method calling another. If the consumer is written by a conscientious programmer, then s/he will check the return value / catch the exception (or knowingly allow the exception to bubble higher). In this case, the overall system works well, no matter if the facility producer (the method called) throws an exception / returns an error condition or not.

 

However, if the caller is written sloppily, or quickly, it is unlikely that the caller will check the return value / catch the exception (when appropriate). If you use return values, the error is simply lost, and the internal logical consistency of your system has just been – silently! – destroyed. Your system may continue to do something useful, but most likely, it will fail in a subtle, hard-to-diagnose fashion.

Categories: Linux, Utilities

GNU Moe Tutorial/Review

Yesterday I was looking at a listing of updates for free software projects. I commented that the package GNU Moe could be used as a replacement for nano or zile, that is, when you need to quickly edit files from the command-line.

So today I’m giving it a go. I downloaded moe via the GNU project’s FTP server and installed it. The compilation was insanely fast, I think it took less than 10 seconds to get it all built and installed.

This blog post is a small tutorial (and a bit of a review) for using GNU Moe and is actually being written in it. I’m learning as I’m doing and this is usually the best way to learn anything. The manual for moe is, well it doesn’t exist. When you first enter moe you are confronted with a blank screen and a title bar at the top of it.

The title bar lists:

  • the command key being used (if any)
  • the current mode of the text editor, either “I” for “Insert” or “O” for “Overwrite”
  • the name of the file being edited
  • whether it has been modified and needs to be save
  • which line you are on
  • which column you are at
  • the time (in 12-hour clock with no AM/PM indicator)
  • a helpful reminder telling you to press “F1 for help”

In comparison, nano only tells you the version of GNU nano that you are using and the name of the file. Nano also helpfully lists some commands at the bottom of its screen.

Press F1 For Help

The first command key I used was of course "F1", the help key. GNU Moe uses the function keys for saving files, loading files, undo and redo, the options menu, the buffers menu and some other things which I will get into as I come across them.

The second command key that I used was Ctrl+C. If the current file being edited is Modified, it will ask if you want to “lose your changes”. If you press “n” meaning “No I don’t want to lose my changes”, it will save the file. I think this is better than asking if you want to save your changes. The way the question is posed is different and highlights the fact that you will lose whatever you were working on.

GNU Moe Gets Out Of The Way When Typing

In terms of typing, GNU Moe hasn’t gotten in the way at all. In fact, it has provided two useful command keys; Ctrl+Y which kills/deletes a whole line of text, and Ctrl+B which re-formats a paragraph by wrapping it at a certain column (I think column 72). The re-formatting is very useful when you’re on a regular terminal. Right now I’m in the shell that you get before running any desktop system. The screen can only handle 80-character columns right now. You can set the column to whatever you like in the Options menu (accessed by pressing F10).

Okay, I just pressed F2 to save the file. It asked me for a new name or location for the file, but luckily it already provides the same name as before. So saving the changes is a matter of pressing F2 and then the Enter key. You can also save and exit moe by pressing Ctrl+X. After I’m done typing here, I’ll definitely be using that, heh.

To load a file, you press F3. As soon as you open more than one file, they are loaded into separate buffers and then moe gives you access to the buffer menu. You can access it by pressing F11 and it lets you switch between the different buffers by choosing from the menu or pressing a number key. To get rid of the buffer, you press Ctrl+C.

So far GNU Moe is very easy to deal with, it all seems self-explanatory.

One thing to watch out for is the behaviour of whatever terminal you’re using. The GNOME Terminal wouldn’t let me use the function keys properly and the same was true of xterm. Another thing is the key bindings. They’re kinda like Emacs’s key chords, though not all of them are like that. There are four different prefixes for the key chords: “[“, “O“, “Q“, “S“. The first prefix is the most commonly used one, while the other three are used for special commands.

If you’re interested in IDEs rather than simple text editors, I recommend checking out PyCharm if you’re a Python developer and either Emacs or Intellij IDEA if you use other programming languages.