Anyone who has programmed for any length of time has an opinion about comments in code. They're essential. They're not essential. Commenting is actually worse than not commenting. It runs the gamut. I'm beginning to understand more and more that comments are actually a disctraction to clean, clear, concise code. Especially when writing in Python, it is possible to write code that requires no comments, but is still 100% understandable and discoverable. Sometimes a line or two is required to explain something not clear from context, but it's rare.
After reading a piece by Steven Smith entitled Comments in Code Indicate Functions Trying To Escape, my lead programmer Troy Melhase (i.e. my "boss"), who is a strong proponent of clear code/no comments, wrote:
Yes. Instead of writing comments, write code that doesn't need
comments.
Clear, and concise, just like his code. After musing on it a while, his ironic streak kicked in, and he composed the following "epic tome," as he describes it, that so clearly illustrates the many useless blocks of comments I have seen in my time as a programmer. He gave me permission to post it, so here you go! Enjoy.
(BTW, visit Troy's blog. He's written a Java to Python translator, and has a really cool stock-trading and analysis application.)
# ## Summary: Explain why excessive comments suck. ## ## ## Author: Troy Melhase ## Email: troy@gci.net ## Date: 05/01/2008 ## ## ## Detail: ## ## Comments like this serve no purpose because you have to read all of the code in this file anyway. ## So here you are, reading useless information that I put here to satisfy a thoughtless policy ## or an academic belief. I could explain what the code does, but it's easier to blat out mindless ## drivel that is easily mistaken for insight or actual work. ## ## Even if I do add useful information to the code below (doubtful), someone will have to edit this ## information as the code changes. That's like writing the code twice, and of course that doubles ## the chances of introducing a bug. ## ## Plus, I've distracted you from your purpose -- reading! Reading code can be difficult without the ## additional burden of constantly shifting gears between executable code and non-executable code (these ## comments). ## ## If you've made it this far without giving up, you should realize that I've still added zero information ## to the subject and wasted your time in the process. The original reply is still better, and you should ## aim to adopt it as professional and personal coding policy. ## ## In case you missed the original reply, and in hopes of finding it here, buried at the bottom of this ## epic tome (aka epic fail): Instead of writing comments, write code that doesn't need comments. ## ## ## Plus: extra file encoding type cruft. ## Plus: extra editor hint cruft. ## Plus: extra version control meta data cruft. ## Plus: version control history that should be left in the version control system. ##
Now, this doesn't preclude documentation--we use doc strings at the beginning of files, functions, and classes quite heavily--but in-line comments in code are rare.
"There are a lot of nice things about PHP, it's just that the language isn't one of them."
from Paul Bissex
'Nuff said
I came across this writeup a couple months ago, and composed a reply (via an e-mail to a colleague), but never posted it.
Some people think objects have failed.
My response:
Objects have "failed" in that they've tried to be the be-all, end-all solution to all problems, while not being powerful enough to be the be-all, end-all. On the other hand, they've succeeded in that they are a good (often great) tool in many cases. I often find that objects are nice just for state-encapsulation: keeps me from worrying about certain details at that moment; I might not even be abstracting anything of note.
And I think it comes down to this: procedural, functional, and OO programming tools are just that. You use one or the other where they might be the most appropriate and most practical. Take these few lines from a script in a project I'm working on: (disclaimer: yes, I wrote them).
file(os.path.join('.', full_name, f.rstrip('.tmpl')),'w').writelines( string.Template(file(os.path.join( os.environ['TACKDIR'],'template-manage',f),'r' ).read()).substitute({'mod_name':mod_name}) )
That is an interesting combination of functional (only two state variables: 'f' from a surrounding loop, and full_name) and object oriented (file and string.Template methods) programming. And the combination works, works well, and is only one logical line of code, to boot.
I don't think it's a matter of object, functional, or procedural styles failing, it's about having a good knowledge of all three, and their capabilities, and being able to make realistic and practical decisions about what will be the best in a given situation. It's also about using a language that lets you combine the three in a mix that works best for you and the given requirements.
(In this case, that language is Python, but that's peripheral.)
In my job at EE Internet, we do a lot of remote data collection, including collection from cameras. Now, the makers of these cameras have figured out how to put the date and time as a graphic in the image itself ( Umiat Airfield) but for some reason they haven't figured out how to embed that same information in the EXIF Data for that image. Very aggravating.
So, Python to the rescue. I came up with a script that extracts the area given, converts it to black and white, inverts it (because these cameras have light text on dark background, and OCR doesn't seem to like that), and then feeds that file to a command-line OCR program. It then takes that text, parses it for the date, and then prints it out in any date/time format desired. Works quite well.
Here it is in all its glory.
Comments, improvements, critiques, etc., are always welcome. And yes, you can post comments pointing to another program/project/whatever that does what I did and does it way better. 
- It requires Python's PIL image library
- It defaults to using the gocr command. This is available in the 'gocr' package in Ubuntu. It also seems to work well with ocrad, which is also available in Ubuntu.
- There should not be any symlink vulnerabilities in this as the exclusive lock is kept on the file while there is data being written to it. Once the data is written, and the file is closed, then it is passed to the OCR program as an input file. Then, it is removed.
UPDATE: Modularized it so you can call it from the command line, or import it into your own Python script and call it that way.
Jon has a post about getting started with Django. Welcome to Python, Jon. I'm sure you'll enjoy it. As I've posted about before, I've greatly enjoyed my foray into the world of Python. While sticking with "pure Django," especially if there is a CMS system on top of it, may mean you don't see Python much, if you start creating filters and editing templates, you'll probably dive right in to the language.
If you have programming experience, snag a copy of Python in a Nutshell. If you don't, grab Python in a Nutshell and Learning Python. Both have served me well.
And of course, if you have a question, ping me. I'd be glad to share what I've learned in my short, but productive eight months of learning Python.
Python is a fun language, and easy to learn. I'm sure you'll have a great time.
Way back in the early days of my interactions with the Internet (1996), I started learning the Perl programming language. I had a client who wanted to create a database-driven web site, and before I realized I had no idea how to do that, I said, "I can do that." Well, my search (probably on the term "CGI") led me to CGI Programming on the World Wide Web by Shishir Gundavaram. Since that book used Perl, I learned Perl, my first "real" programming language (I had learned a little bit of C64/MS Basic before that).
Fast forward ten years. By now I've done a few database-driven web sites, a few C/C++ projects, and a fair bit of database design and programming (in Visual Basic). Should mean I'm a Perl hacker for life, right?
Well, maybe not. Around the end of last year, I had just completed a 500 line script in Perl that extracted data from files, and generated pages and diagnostic data. After that, I realized that I did not want to code my entire Master's project in Perl. Keeping track of the data structures became a nightmare, and I realized how much I struggled to wrap my mind around the syntax, instead of it coming naturally and efficiently. I needed something better...at least something that worked better for me.
[I pause here to note: this is not a flame against Perl. As I stated, I used Perl for 10 years, and enjoyed using it, and was very productive using it (at least in smaller scale projects). I just came up against a project and domain where Perl wasn't the best fit for me. It may very well have been the best fit for someone else. We now return to our regularly scheduled blog entry...]
I'm familiar with a lot of languages, but as stated, have only used Perl, Visual Basic, and C/C++ in any real capacity. I had heard a lot about Python, and knew enough to know that I'd probably enjoy the way it's set up. I like organization, and one of the ways Python organizes things is by using indents to denote blocks of code: all code at a particular level of indent is in the same block. An example, using classes, methods, and 'if' statements.
class DemoClass(object) #inheriting from object denotes a "new style" class _init_(self, name): # Do some initialization here self.name = name def sample_method(self, var): if(var == 'this'): print "That!" elif(var == 'thus'): print "Thusly!"
And there you have a fully functional python class. Python's class syntax is so intuitive to me that I've used (that is written) more classes in Python in the past few months than in all my years of Perl programming. In addition, I find the syntax to use objects in Python to be more natural, and less to type for that matter.
-- '.' instead of '->' as the object accessor. It's just easier to type.
-- Calling the class name as the constructor instead of PackageName->new() makes more sense to me.
-- Declare a class with 'class ClassName' instead of the several lines it takes to define a class in Perl
There are other reasons and areas as well where the syntax, semantics, and philosophy of Python just makes more sense for me, and I may write on those in a future post.
You can read my evaluation and reasons (complete with Typos) which I wrote for my boss and coworker to justify coming up to speed in a new programming language for my Master's/Work project.
To sum it all up, "I'm really liking and enjoying Python." I rewrote that aforementioned 500 line script, and added even more functionality, and ended up with not much more code. The language was very natural to learn, and it was very easy to come up to speed with the functions I needed. I've written about 1000 lines line python so far...I think I've hooked.
Tonight I was reading through SourceForge's newsletter, and one of the top 25 projects is a relatively new one call ThinWire. There are a lot of existing frameworks out there for making AJAX applications look like "desktop applications," and often they allow you to dispense with programming in HTML and Javascript. Examples include Morfik, Google Web Toolkit, and even a Python version: Pyjamas. With most frameworks, while they looked good, they were often heavy (large download), or left something to be desired in the aesthetics department. Thinwire looks to change that. Take a look at their Playground Demo for examples of the full range of the tool kit, then look at their mail demo to see just how close to the "desktop feel" they get. They are even working on a graphical form designer that is written using the framework itself. Now there's power! And they claim in only a 100K download. Lest you think this is a toy framework, they also have a video showing a production application written using ThinWire. From their site:
This application has over 300 data input forms and dialogs with a wide range of complexity. It has a business rules engine that toggles the visibility of fields, required state of fields, limits dropdown options and much more....There are no page refreshes involved in updating anything within ThinWire®, the page is modified on the fly as a result of user actions that trigger event listeners on the server. Like all applications built with ThinWire®, no client-side code or HTML was written; all logic resides on the server.
One teaser that caught my eye is on their front page where they say you can develop using Java, or "alternatively, use a scripting language." I can't find further explanation of that, but if I could program in this framework using Python, I think we would have a real winner.
They are gunning for the Duke's Choice Award, so if you have experiences with ThinWire, or want to try it out, they are looking for company and developer feedback as part of the nomination process. I'll certainly be following the development efforts.
If you're starting to end sentences with semicolons try Python. My new primary language. I have a draft saved at the moment about my transition to Python. Short story: I'm loving it. Stay tuned.
|
