Web Development
No, this isn’t a blatantly obvious attempt to generate reader feedback. This is a look at why developers should use well-commented code throughout their projects and how this seemingly simple addition can change the world–or at least, make people’s lives easier.
What are comments?
//this function does x
or
#this line does y
These lines of text are comments. They may have slightly different syntax, depending on the language used, but their purpose is the same–to quickly inform those reading the code exactly those particular lines do.
Why you should comment:
1. It helps other people understand it. This seems like a no-brainer, but you never know when someone else might need to understand your code. If you release the code under certain licenses–GPL, GNU–or another open source, it is important for those who will obtain the source code to be able to modify and add to the overall functionality of your code. Even if you aren’t releasing it under an open source license, consider the fact that someone else may eventually have to fix/add to it. I’ve personally have come across some intense code (spread across several dozen files) without any documentation and unraveling how all the pieces fit together took longer than the actual repair.
2. It helps you understand it.Comments can help you quickly troubleshoot an error. You exude a certain confidence when you are able to tell someone “I think I know exactly what’s causing that.” In addition, you never know when you might have to put down the code and come back to it later. If you’re looking to extend your code, you can easily remember what everything does and can better integrate any additional functionality.
3. It helps you write better code. After seeing a need for several occurrences of a similar command, you may be able to condense your code as a result of comments. You also have a chance to logically address and document each step as it occurs, so you may consider errors or other situations that you might not have otherwise.
Well-Commented
The key word here is well-commented. You don’t need to comment every line. In fact, it’s often better if you don’t since comments, as a general rule, shouldn’t match exceed the amount of actual code. Comments should describe the overall functionality of several lines, or help to define variables or cases that otherwise may not be readily apparent to someone reading your code for the first time. You must assume that the reader does have some general knowledge of the language in order to avoid overloading with comments.
//This is a blatantly obvious attempt to generate reader feedback. Please use the following form to share your experience with commented code–or, if you aren’t a developer, a similar experience.
Peter Burgin is a web developer and instructor who’s not afraid of debugging, large textbooks, or speaking in front of huge crowds.
All Posts, Web Design
One of the things we web designers often talk about when we’re around each other is our client stories. And while I won’t get into most of the topics or details, I do want to highlight a few important ones that are pretty common. Those being, clear understanding of responsibilities of the designer, of the business owner, on-time deliverables, and contract and payment.
I like to refer myself as a junior web designer. This because I haven’t been around for over a decade doing web design, but I have been around long enough to experience the highs and lows of the industry. Especially when it comes to my responsibilities as a web designer. First and foremost, I am to be the authority on such a subject matter when it comes to my clients. I must assume they know nothing, and take the time to adequately discuss anything that doesn’t make sense to the client. I’m not saying that non industry people are handicapped at all. But I do think its unfair to talk a bunch of techno babble under the pretense that a client understand everything I’m talking about. I also believe I have a responsibility:
- To return phone calls or emails in a timely manner.
- Clearly explain my prices and estimate for work to be done
- Ask questions about what the client would like to see done
- Get existing examples of websites & designs that the client likes
- Secure a deposit before work is started
From a client’s side, there can be quite a few things needed that may not become clear until deadlines are approaching. One example is “content.” It is always the business owner’s responsibility to provide content for their website. As a designer, we can easily charge for copyrighting if necessary, but otherwise it’s up to the client to take the time to write out their bios, services, products, prices, and even provide the graphics and logos for the site. In a lot of cases this is where pricing for websites starts to climb. What at first seemed like a $1,500 job has now turned into a $2,600 job after creating graphics, artwork, content, research, and implementation. I can’t stress how important this is because of how it will seriously drag a project that would normally take 2 weeks into several months of back and forth missed calls and unanswered emails.
Milestones for each web project will vary, but each project has them. From getting a contract signed with initial payment, to full site testing and launching, there are some goals that need to be tracked and reached before further work is started. Most designers will keep the client informed with over estimated time lines. This is not because we’re lazy or anything, its to give enough time to get things in order or received from the client with a realistic turnaround time for completion. If we think we’re going to be late on a deadline, its our responsibility to inform the client. If the client can’t seem to finalize something – they need to understand how that affects the overall time line for their project.
My last point is securing a contract and payment. Let me skip to payments because this is dearest to just about every freelancer out there. We need this upfront not because we need to pay our overdue light bill. Its more so because we need to get you truly interested in getting us the materials we need to really undertake a project. If we don’t secure a preliminary deposit from you, we’ll most likely be waiting for months before hearing anything from you. I won’t generalize that statement to everyone, but I will say most. Each designer has their own way of breaking down a project’s payment percentages, but their important to sticking to the deadlines.
Now as for a contract; this is important to all parties. A working contract protects the designer for their work, what is fully expected of them, and also the client for what is eventually owned/owed to them.
All Posts, Web Design
Fellow web designers, I know we’ve all been there. Had a great prospective client meeting. They loved your portfolio of work. Contacted you from a referral of a previous client. So you’re feeling great about this project going into it. You make a draft, show it to them, and it all starts going downhill from there. They want more revisions, the logo needs to be changed, content can’t be agreed upon, and more and more. Originally you quoted a certain amount and now your billable hours have almost tripled and the site isn’t even half way done. You ask yourself, who’s really at fault here? Without getting into any formalities, lets keep most of the blame with the client.
When I first started out, I used a contract with my first client. Ironically, it saved me from an issue once the site was completed. They wanted the workup files and my contract specifically said they’re not included. After some phone calls, emails, and threats from their family members, I stuck to my guns and referred back to the contract that was signed. Could have been worse had I not had that agreement setup from jump right? Well, this type of story is all too common on this side of the fence.
Contracts don’t necessarily have to be only for the protection of one person. The current contract I have and use now actually is quite easy to read to not hard on the eyes for my clients. Really want a contract does is protect the property of each binding party and set rules and understandings of work or a relationship.
Below are some general categories you’ll want to use in your own contract if you don’t have one already:
- Authorization
- Agreement
- Scope of Work
- Payment Schedule
- Confidentiality
- Hosting
- Terms
- Project Guidelines
- Files and Ownership
If your a freelancer doing jobs here and there, a typical surface level contract should do. However if you’re working as a subcontractor or with bigger businesses that are outsourcing work to you, a contract written or reviewed by your lawyer may be your best option. It would be a wise investment in the beginning that may save you thousands in the future.
Have some tips on contracts? Let us know in the comments below.
