With good names for packages, classes, methods, variables,... code should be self-explanatory. Long method names are not a problem if they really make code read better and don't reveal too much implementation details. Names are more powerful than most developers usually think, they have a profound impact on our designs. In general names should be pronounceable but there are always exceptions.
- In a small loop, it's OK to name the index i, j, k or something like that you don't have to say
theLoopIndexWhatever. In fact, "i" reads better in a short loop.
- Methods should not contain concrete details, those should be parameters instead:
Should better be written like:
- Method names should say what they do, but not how:
Should may be:
- The name of the class should be considered when naming methods. The name of the methods should be considered when naming its arguments. Given that methods should not have more than 3 parameters (the less the better), the names of the arguments may be combined with the name of the method, specially if there is a single parameter. Good names care about their context.
result = expressionResolver.resolveExpression(expression)
Reads better like this:
result = resolver.process(expression)
- In the case of test methods, the name should describe the behavior without concrete details. The details are inside method body. The test method name is the description and the body is the example:
- Names should not contain technical details, like the types , because they are an excuse not to search for proper domain names. Modern IDEs provide enough help for the programmer to find out types, code should be business domain oriented.
Avoid prefixes and suffixes like "Abstract*", "I*" (ISomething), "*Impl"...
Don't let the syntactic noise bother you when choosing your names, the fact that there is a brace in the middle should not impede you from writing a line of code that reads like well-written prose 😉
I'll probably will go on updating this post with more examples.
I am using LeanPub to create some manuals and it's a very nice service. You just have to use Markdown to write your document and it generates a good looking pdf document from it. Well, as far as I've read today it's actually kramdown a superset written in Ruby. Everything was fine but that my partners wanted to add a custom header image in the manual. This is not supported by Leanpub, in fact it's not supported by Markdown as far as I know. So I decided to manipulate the pdf using my preferred OS (linux). It's not easy!
Pdftk (the pdf toolkit) is great!
pdftk it's a powerful command line tool to manipulate pdfs. The tool that has saved me eventually. Thanks Sid Steward! What I've done is:
- Use LibreOffice to insert the header image into an empty document and then save it as pdf (header.pdf)
- Use LibreOffice to create a cover for the book (cover.pdf)
- Remove the first two pages from my_book.pdf, generated by Leanpub:
pdftk my_book.pdf cat 3-end output tmp.pdf
- Add the cover:
pdftk cover.pdf tmp.pdf cat output tmp2.pdf
- Add the background:
pdftk tmp2.pdf background header.pdf output my_final_book.pdf
See more powerful examples of pdftk.
Things that didn't work so well:
- Xournal: this tool is great when it comes to adding some text to a pdf document among other things. Probably the best pdf tool with GUI I've tried. However, it doesn't support adding images or headers. There is a patch to insert images but I didn't spend the time trying to compile it.
- PDFedit: looks powerful but I didn't know how to use it. I could remove text from the document easily but nothing more.
- uPDF: looks interesting but it's buggy, like experimental. It didn't work for me, freezes when saving the document and the GUI is quite hard.
- PDF Mod: this one is looking very good! but I knew about it when I already solved the problem and didn't try it out. The doc says it modifies pdf but I don't know whether it supports headers/backgrounds and things like that.
- LibreOffice-pdfimport: Right, it opens up the pdf document but it looses its format and images at least for my pdf book.
- Pandoc: In desperation I tried to generate the pdf myself skipping Leanpub, from the markdown text. Pandoc is brilliant and very powerful converter. Together with latex-beamer it has generated a pdf for me:
pandoc -t beamer -o my_book.pdf -i my_book.txt
The problem was that I don't have a nice latex template to use so I just loose all the nice formatting provided by Leanpub.
I also tried two commercial tools for Windows but none of them were very good either. The prices were reasonable so I though I would just buy them but the trial version was good enough to realize the software wasn't good.
This story has taken me way much time I thought, I hope you save some time reading this if you face the same problem 🙂