Unexciting Coding [modified]
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
Amen. I once worked with a very senior person who said that comments were worthless, see the code, the comments are always out of date. So he didn't write them, and wrote frightfully elegant code (if you know what I mean). I've had to maintain other folks old code. Knowing what they had in mind can be *very* useful, esp if the code doesn't agree. Also knowing history - what changed, when, and why is useful. I'm not a mind reader, esp if they're long gone...
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
Good advice, good spelling, and good grammar. Apparently, you can imagine my surprise to find all these things in the same place on the web. Good job.
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
-
John Simmons / outlaw programmer wrote:
- Never assume that someone knows what you were thinking.
John Simmons / outlaw programmer wrote:
- Don't be afraid to be verbose.
John Simmons / outlaw programmer wrote:
- USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults.
These points go well to be presented to the ones who ask questions in the programming forums too. Especially #1 - I can't explain how it feels like when someone says this: "It is not working... Plz help". Breaking the rules #1) #2) and #4) together in a single post.
It is a crappy thing, but it's life -^ Carlo Pallini
Agreed, I shutter when i see incomplete posts from new programmers. I understand they need guidance but man it takes 9 posts just to get the details out of them and by then they figure it out since you showed them what a "Stack Trace" is and how it helps.
-
I agree and I would find a better job as fast as I could, just because bad habits and practices are very difficult to overcome once they are settled.
Couldn't agree more, worked for a crappy place that also "let" me to IT work in my "Spare" time. Boss was lazy :zzz: , and it slowly effected me X| , now at my new job I am slowly breaking that habit :-D now that I have a boss and good mentor to reflect against. Get out while you can.
-
in front of a method/class variable in C# type
///visual studio will expand it out into a stub for you to fill in.Today's lesson is brought to you by the word "niggardly". Remember kids, don't attribute to racism what can be explained by Scandinavian language roots. -- Robert Royall
By far one of the best features. Man I think i use that everywhere, especially when i have multiple (having trouble remember word :doh: , going to comments....) overloads in C#. ie: public class TaskManager { private void DoTask() private void DoTask(string TaskName) private void DoTask(string TaskName, bool ASync) } Now what do you think each one does? Sure helps me :) . And if I call DoTask do you think if there are no tasks to do it throws a exception. because it sure the hell doesn't have a return value if it succeeded. Or does it fire a event for when the task is complete, or does it only to that when "Async" is set to true? What if there is no task name..... My 2 cents..
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
-
Didn't he forget to say PLZ? :rolleyes:
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
I'd add one more thing: If your system keeps a log for *any* reason, then instead of inline comments, write a function that writes a time-date stamped time to the log, then put your inline comments into string parameters for that function. It'll help for finding any logic bugs in your system.
-
in front of a method/class variable in C# type
///visual studio will expand it out into a stub for you to fill in.Today's lesson is brought to you by the word "niggardly". Remember kids, don't attribute to racism what can be explained by Scandinavian language roots. -- Robert Royall
-
Yes, and I concluded it is all our fault :~ Good habits are usually boring, difficult or tiring to maintain. And often, takes time. Bad habits are usually the easiest and quickest path and very "lazy-friendly".
Fabio Franco wrote:
Bad habits are usually the easiest and quickest path and very "lazy-friendly".
Plus they often feel good. :-D
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
-
Thanks for a great post - totally agree with these points. Another thing I'd add is the "free" comments provided by sensible, meaningful names for everything - variables, parameters, methods, etc. They might take a bit longer to type, but in my mind contribute enormously to code clarity and maintainability.
Elizabeth Connolly wrote:
meaningful names for everything - variables, parameters, methods, etc.
I agree. Coming up with good names is often harder than writing the algorithm. And it often needs to be iterative too. Refactoring tools for renaming help enormously here.
Kevin
-
I'm sitting here at home, waiting for the DirecTV guy to show up, and thought I'd work on some code for a new article I'm writing... Writing code for a CodeProject article is fun, and can be quite fast when you make certain assumptions about the objects being used and data being manipulated. Once you get it working, you think, "Ahhh, it's almost ready to release." Of course, my desire to release the code is almost always tempered with a desire to make it self-documenting and somewhat bulletproof. Adding comments and exception handling is tedious drudgery - something I equate to ditch-digging, yet it needs to be done. You have to be a philosopher (no matter what you do, it seems like it's never enough) and a clairvoyant (anyone using this code might try this or that) to perform this task effectively. I've been working for three hours, and I've only covered two classes. In the end, it's a pain in the ass, but I bolster my attitude knowing that even if my efforts might not be appreciated by a single person, I'll be able to maintain the code properly in the future. I have advice for anyone just starting out as a programmer, regardless of the language or platform you're targeting: 0) ALWAYS comment your code. It's best to do it as you go, or at least once you've completed the bulk of an object's code. If you don't comment as you go, you probably won't have time to go back and rectify the situation. Being lazy up front causes maintenance problems down the road. 1) Never assume that someone knows what you were thinking. If there is ANY question about your intentions, document it in comments. 2) Don't be afraid to be verbose. Partial sentences can sometimes convey an incorrect perception of what the code is doing, and why it's doing it. Comments do NOT cost anything as far as the compiled size/speed of your assemblies are concerned. 3) In the case of Microsoft tools, Make appropriate comments within the Intellisense system. There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only. 4) USE COMPLETE WORDS! Code commenting is not a valid "texting" environment. Using things like "Ur", or "plz" just pisses off the adults. 5) Every property delegate, constructor, and method should have an Intellisense comment. 6) Make it a practice to appropriately comment your own personal code, and you'll find it easier to do in code you write for your employer/customer. 7) If there is a possibility that another progra
You get my 5. :)
John Simmons / outlaw programmer wrote:
ALWAYS comment your code
Nothing is worse for the soul than having to maintain code that has literally zero comments. :wtf: This has happened to me in a couple of contracts recently. :mad:
Kevin
-
I believe that it works in all project types with VS2005 and VS2008. I haven't actually tried it because I stopped doing C++ more than a year ago, but I don't see why it shouldn't work.
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001 -
Good advice, good spelling, and good grammar. Apparently, you can imagine my surprise to find all these things in the same place on the web. Good job.
:) I was educated on the east coast (Maryland) in the 60's and mid-70's, when they were still actually teaching kids how to read and write.
"Why don't you tie a kerosene-soaked rag around your ankles so the ants won't climb up and eat your candy ass..." - Dale Earnhardt, 1997
-----
"...the staggering layers of obscenity in your statement make it a work of art on so many levels." - Jason Jystad, 10/26/2001 -
John Simmons / outlaw programmer wrote:
There is NOTHING that pisses me off more than trying to use an object and finding out through trial and error that a property is read-only.
Boy do you have problems! :laugh: I'd say you should always document your code, preferably using the xmldoc feature, but you shouldn't always comment it any further than that. Avoid comments that only say what the code does when the code itself says it much more clearly. It is worse than useless to write
// Increment x by one.followed by the statement++x;when the statement alone conveys exactly the same information while taking up less of my time. So the first rule is if you're going to do it, do it properly. I personally find that the xmldoc approach of summing up what a method or property is supposed to be or do is often enough. If the code is hard to understand even when you know what it's supposed to do it may be that the code isn't all that good. There are times when comments on implementation details are really needed, but it is very seldom the case that a single line is enough to write anything helpful in such cases, because the code will then be complicated. I personally like to use a#regiondirective in these cases to write a longer explanation of implementation details that can be easily collapsed out of view once read so it doesn't get in the way of the code. Finally, the right time to write the xmldoc is not immediately after implementing a member, but before implementing it. Not necessarily immediately before, but definitely before. It is a very good habit to work out what to make before making it, something that is harder than one might think, and declaring at least the public members of a type and documenting what they are/do before we code is actually a very good way of clarifying in our own minds what exactly we're doing prior to doing it.I have to agree on writing comments before implementation. A great way to finish up the design of the code, and speed up the implementation process. For my senior capstone project in college, my partner and I spent about a month designing our program, then about a couple of days filling in the basic class and function structure (no implementation, just the major empty functions), and then about another week writing most of our comments. THEN we started writing real code. Man was I happy we did that! It made the coding phase so much easier. Brandon
-
and let us say AMEN. Something I add to a project as soon as it's started: projName.ver - a text file. It contains a narrative, updated each day the code is worked on, describing what was done. Although somewhat useful at the development stage, it's particularly useful as changes are made down the line (whether they be bug fixes or modifications). The beauty of this is a single place to go to look for what happened when and why. Referencing the date with the outbreak of a bug and you know just where to go back. The above is the top of three tiers. The next tier down is a header describing the purpose of the code (comments just after the declaration and before first line of code) which describe what changes were made and those "what was I thinking" moments. These comments are often extremely similar to the appropriate parts of the .VER history, often being used to create parts of it. The final tier is comments on (or above) virtually every line. The 3-tier system gives two tiers of context for the comments. When it does, eventually, pay off, it is (As You Obviously Know) a great thing. In the last couple of weeks, an application I wrote three years ago finally went live. I was so greatful to me for not leaving any mysteries to solve when modifications and additions were requested. The stuff you wrote is just great. As one would expect (even hope?), we each develop our comments with a certain style. I'd be interested in any other styles others would care to share.
"The difference between genius and stupidity is that genius has its limits." - Albert Einstein
"How do you find out if you're unwanted if everyone you try to ask tells you to stop bothering them and just go away?" - Balboos HaGadol"It's a sad state of affairs, indeed, when you start reading my tag lines for some sort of enlightenment?" - Balboos HaGadol
I nearly always include a history.txt file. And I reference the release version # too. For in-module comments, I write a standard formatted comment block: '* Purpose: What the module is supposed to do '* Accepts: What params it accepts (optional) '* Returns: What it returns (optional) '* Mod1 : Purpose of the 1st mod '* Mod2: : Purpose of the second mod (added when major mods are added, so not every module gets one) '* Author : My name, and quoting any contributing authors '* Date : When the module was written '* Mod1 : Date when mod1 was added '* Mod2 : Date when mod2 was added, etc Then I write comments BEFORE I start writing any code: '* Get the parameters from the config file '* Make a connection to the database '* Get the remaining parameters from the db '* Present them to the user as a dialog '* etc Then I write the code I signify comments I want to keep by using '* (as against just ' for temporarily commenting out code)