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
Exciting ... Absolutely excellent post and lucid writing, John ! imho this IS an article. This deserves to be "pinned" on some special forum on CP, I think. Perhaps the "Hard-won Knowledge" forum :) ? "Diamonds from Carbon forum" ? thanks, Bill p.s. When I was on the Illustrator 3.2 team at Adobe, at one meeting someone announced they had gone through the voluminous source and found fifteen or so separate places were a hexadecimal conversion routine was implemented :) So, perhaps, we do not live by comments alone ? p.s.p.s. I explore programming through prototyping, through setting myself small tasks that "force" me to master or use certain facilities in some semi-pragmatic way. I find I have to keep a working text document open (I use UltraEdit) to make notes in on a daily basis about why I did certain things I did, and what were the open issues when I stopped : these being about strategy that is kind of "meta" to the coding iteself. I imagine there's a better way to incorporate this in the source itself that I'm not hip to, being a self-taught mutant who didn't go through academic computer science. Of course I can force VS to bind the text document into the project.
"The greater the social and cultural distances between people, the more magical the light that can spring from their contact." Milan Kundera in Testaments Trahis
-
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:
- 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.
I'd add that it will help you understand your own code later too. Quite often, a year after I had finished some code and needed to return to it, without proper comments, I was just staring at it and thinking, "yeah, it looks like my code, but what was the point of having this
< whatever >? There had to be one" :-O -
John Simmons / outlaw programmer wrote:
- 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.
I'd add that it will help you understand your own code later too. Quite often, a year after I had finished some code and needed to return to it, without proper comments, I was just staring at it and thinking, "yeah, it looks like my code, but what was the point of having this
< whatever >? There had to be one" :-Odmitri_sps wrote:
Quite often, a year after I had finished some code and needed to return to it, without proper comments, I was just staring at it and thinking, "yeah, it looks like my code, but what was the point of having this < whatever >? There had to be one"
A YEAR later? How about 2 weeks later :omg:
Jason Brown C# Developer
-
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
Hey, I like the fact your numbering starts from zero -- nice touch!
-
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
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. -
FyreWyrm wrote:
Too bad my company's coding standards pretty much forbid everything you mentioned.
You're working for idiots. Find a better job with smarter mentors - quick, before you're ruined for life. :doh:
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
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.
-
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
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.
-
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
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
-
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
-
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.
Fabio Franco wrote:
bad habits and practices are very difficult to overcome
Have you ever wondered why bad habits are so hard to overcome, but good habits are so easy to lose? :sigh:
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
-
Fabio Franco wrote:
bad habits and practices are very difficult to overcome
Have you ever wondered why bad habits are so hard to overcome, but good habits are so easy to lose? :sigh:
"A Journey of a Thousand Rest Stops Begins with a Single Movement"
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".
-
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
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..