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.)
The interview is long over, the offer letter has been signed, and my two-week's notice has been given, so now the story can be told. As many of you know, for the the past year and a half I've been working at EE Internet. The time has come to move on.
A few weeks back, I came across a job posting on the AK LUG mailing list from a company in Anchorage looking for developers (programmers). I replied and asked if it would work as a telecommute job from Fairbanks. The answer was: "It's a slim chance, but let's give it a try." So, after sending them my resume, I flew down to Anchorage for an interview on September 25th. They liked me enough to make the telecommuting thing work, and I start work on November 5th.
I'll be working for S&K Aerospace a Montana native corporation, and the only non-Alaskan native corporation doing business in Alaska. They are a military contractor developing technology solutions for the armed forces in Alaska. I will be doing web application development, mostly in Python (woohoo!).
The best part is, I'll be working from home, so will get to be around my family so much more. We're all looking forward to it, and are very thankful for this opportunity. Crystal and I have been praying for a work-from-home job for me probably as long as we've been married, and God provided this job.
I'm excited!
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.
In previous posts, I've alluded to the fact that I was learning Python for a project that was getting under way at work. I never did say what the project was, however, so here we go.
The company I work for, Engineering and Environmental Internet Solutions (EEI) is a sister company to Global Watersheds Scientific (GWS). GWS (via EEI) does much remote data collection around Alaska using data loggers connected via the Internet (including satellite), radio, and even cell phone. This data is collected and displayed (both textual and graphical representations) on a variety of web pages, and is distributed to a variety of clients. See this page for an example.
Quality assurance (QA) and quality control (QC) on this data, however, if done, must be done by manual inspection. Needless to say, this is a labor intensive process. The goal of this project, dubbed Photizo, is to create framework that will provide data processing, QA/QC, and data visualization, all in an automated fashion.
What does "Photizo" mean? The project name derives from a Greek word meaning "to enlighten, render evident, to give understanding to." The purpose of Photizo is to analyze data and give insight and understanding into said data, "rendering evident" the function (or malfunction) of a data collection network. Thus, the name Photizo (pronounced foe-tee'-zoh).
We are currently in the design phase, and things are going well. Python will be a good fit for this project, and give us great flexibility in our implementation, especially in areass where we must be able to accommodate various inputs (such as a variety of data file formats) or creating a framework to test data that will allow us to add and modify tests without editing the core code.
You can learn more, and keep track of progress on our wiki: photizo.eeinternet.com. If you have questions, comments, or suggestions on this project, feel free to drop me a line at joshua (at) eeinternet (dot) com.
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.
|
