Do you have this experience?
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Marc Clifton wrote:
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined.
Almost always, perhaps with the exception of when I document at the same time as writing the code. Because that forces me to say what I want at the same time as doing it, I catch and process those same things but at the writing time rather than later. Unfortunately, tight deadlines usually mean documentation after the crunch, and refactoring to remove overlooked/ill-considered design issues. _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
I document my code during coding. I usually spend some time to choose good variable names and to implement at least a basic parameter validation, because - I know myself - I won't do that after coding, I'm lazy :-O ___________________________________ Tozzi is right: Gaia is getting rid of us. My Blog [ITA]
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Marc Clifton wrote:
What about you? (Folks who don't document their code need not reply. )
What about those that write comments, and then go back and add code?! :rolleyes:
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Yes, this happens to me all the time. I generally document as I code, and find that I refine the documentation later. PJC
-
Marc Clifton wrote:
What about you? (Folks who don't document their code need not reply. )
What about those that write comments, and then go back and add code?! :rolleyes:
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
DavidCrow wrote:
What about those that write comments, and then go back and add code?!
// no comment :rolleyes: _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
It seems to happen less now that I write test first. Still, it does happen. regards, Paul Watson Ireland Feed Henry! K(arl) wrote: oh, and BTW, CHRISTIAN ISN'T A PARADOX, HE IS A TASMANIAN!
adapted from toxcct:
while (!enough)
sprintf 0 || 1
do -
It seems to happen less now that I write test first. Still, it does happen. regards, Paul Watson Ireland Feed Henry! K(arl) wrote: oh, and BTW, CHRISTIAN ISN'T A PARADOX, HE IS A TASMANIAN!
adapted from toxcct:
while (!enough)
sprintf 0 || 1
doPaul Watson wrote:
It seems to happen less now that I write test first.
That's a good point, and I would agree, I find I refactor less. One thing I still can't do is truly write the test first. I have to still implement at least a stub class because I think in terms of the "package", and that means coming up with the class name and at least an initial pass at the internal fields, public properites (C# centric) and method names. And at least that way, I can use Intellisense when writing the tests. How about you? Marc Pensieve
-
Marc Clifton wrote:
What about you? (Folks who don't document their code need not reply. )
What about those that write comments, and then go back and add code?! :rolleyes:
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
DavidCrow wrote:
What about those that write comments, and then go back and add code?!
Aye, now there's something you don't see too often, I imagine! On the occasions that I've done that, it works really well. Hmmm! Marc Pensieve
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Oh yes.... for me that is an on-going process though. Management's rush to unrealistic arbitrary deadlines is a killer most of the time. Why is common sense not common? Never argue with an idiot. They will drag you down to their level where they are an expert.
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Yup, this happens to mee to. But it's just because that when you write the code the first time, you have the big picture in your head to follow and implementation logic to think about, so the parameters validation and exception handling (in some cases) just slips your mind. Funny thing is I have always written the code, and after it was finished I started to comment it, and improve it like you said with parameter validation, exception handling, etc. But now I started to comment my code while writting it. Anyhow, because I am aware of what my commenting task was, I double check the code and while I'm at it ... the comments.:-> regards, Mircea Many people spend their life going to sleep when they’re not sleepy and waking up while they still are.
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Refactoring is a way to clarify the code, same as documenting it, so I think it's natural to do them together that way. If I'm short on time, I'll even document thoughts for future refactoring inside the code. :rolleyes: BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright -
Marc Clifton wrote:
What about you? (Folks who don't document their code need not reply. )
What about those that write comments, and then go back and add code?! :rolleyes:
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
Funny, that's how I was essentially brought up writing software. Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan. Cheers, Drew.
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
Yeah, and triply so when you are also publishing a developers API, it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code. I.E. I have a property I set in a Client object, the property has all the business rules setup for a Name field so rather than rewrite it I just copy it to another object and the comments come with it so in the developers documentation it says for a Unit object "Client Name". I can't go through code and resist the urge to clean it up. Particularly code written in the heat of battle just before a deadline. I'm sure an artist looks at work they did in the paste and has to fight the urge to grab a brush and add a little bit here or fix something. How often do we ever get the time to do it though, it's sad really, you just can't have perfection. Or maybe that's Zen. ;)
-
Marc Clifton wrote:
What about you? (Folks who don't document their code need not reply. )
What about those that write comments, and then go back and add code?! :rolleyes:
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
I do that all the time. When I have a complex method I work it all out as pseudo code comments and documentation comments line by line then go back in and write the code to fulfil it. It's a good thing to do for anything complex because it makes you think about it clearly first.
-
Yeah, and triply so when you are also publishing a developers API, it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code. I.E. I have a property I set in a Client object, the property has all the business rules setup for a Name field so rather than rewrite it I just copy it to another object and the comments come with it so in the developers documentation it says for a Unit object "Client Name". I can't go through code and resist the urge to clean it up. Particularly code written in the heat of battle just before a deadline. I'm sure an artist looks at work they did in the paste and has to fight the urge to grab a brush and add a little bit here or fix something. How often do we ever get the time to do it though, it's sad really, you just can't have perfection. Or maybe that's Zen. ;)
John Cardinal wrote:
it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code
Man, I hate this when I'm maintaining older code. I've seen some comments that have nothing at all to do with product, someone stripped the code from another product we sell, and left the comments as they were. It's great to finally read through a procedure (assembly) you thought had nothing to do with what you were looking for, only to realize the comments were completely bogus. X| The 8 Character limit on variable names doesn't help either, but that's another issue. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright -
Funny, that's how I was essentially brought up writing software. Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan. Cheers, Drew.
Drew Stainton wrote:
Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan.
I think this is the goal of any software product, but it also requires that the design goals do not change/evolve during the process. I have seen government projects try this, you spend a year planning and producing a ton (often litterally) of documentation on what you will do, and then spend the next 6 months editing it for the changes over the last year, then the next 3months editing it for the changes over the last 6 months... etc.... by the time you actually start developing to the documentation, you still have to take quarterly stops to rewrite code and update documentation. Or you stick to the documentation and make a product that will never be used. This obviously is not the case for all projects. I do believe there are projects that are best in the design&document first strategy, and there are those that require agile development. The first and hardest decision is figuring out which is which. _________________________ Asu no koto o ieba, tenjo de nezumi ga warau. Talk about things of tomorrow and the mice in the ceiling laugh. (Japanese Proverb)
-
When I go through and document my code, I often end up doing refactoring, things like adding parameter validation, exception handling, tweeks to improve code functionality, renaming variables/parameters/methods so that they are better defined. I find this to be true just about every time I go through and document the code. What about you? (Folks who don't document their code need not reply. ;) ) Marc Pensieve
That sounds pretty familiar. If I'm in a particular area of the code, I tend to look around for any obvious gotchas in either the code or comments/documentation. If I find anything and fixing it appears to be low risk, I'll do so. Every so often I'll also go on a compiler/lint issue hunt and kill any potential nasties that have crept into the project recently too. Anna :rose: Currently working mostly on: Visual Lint :cool: Anna's Place | Tears and Laughter "Be yourself - not what others think you should be" - Marcia Graesch "Anna's just a sexy-looking lesbian tart" - A friend, trying to wind me up. It didn't work.
-
John Cardinal wrote:
it's amazing how often a copy and past operation leaves completely wrong information in the comments despite working perfectly as code
Man, I hate this when I'm maintaining older code. I've seen some comments that have nothing at all to do with product, someone stripped the code from another product we sell, and left the comments as they were. It's great to finally read through a procedure (assembly) you thought had nothing to do with what you were looking for, only to realize the comments were completely bogus. X| The 8 Character limit on variable names doesn't help either, but that's another issue. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright8 Character? WTF? I created this variable just yesterday:
private Guid _MostLikelyRateUnitChargeDescriptionID=Guid.Empty;What could be more important than nice fat variable names that mean what they represent? It's the lowest common denominator in the world of understandable code. -
Funny, that's how I was essentially brought up writing software. Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs. Wound up with pretty tight, well defined code blocks by doing it this way - forces you to stick with the game-plan. Cheers, Drew.
Drew Stainton wrote:
Waaaaay back in 1986 one of my prof's required us to write a user guide as part of the analysis/design. I took that (and the design docs) and developed documented stubs for a good portion of the code and then filled in the code to match the documented stubs.
Same here, only it was in 1989. We were not even allowed in the lab until several weeks later, just to ensure we were not writing code. As a matter of fact, all of my undergraduate CS courses required a requirements/specifications document to be handed in along with the code itself.
"Let us be thankful for the fools. But for them the rest of us could not succeed." - Mark Twain
"There is no death, only a change of worlds." - Native American Proverb
-
8 Character? WTF? I created this variable just yesterday:
private Guid _MostLikelyRateUnitChargeDescriptionID=Guid.Empty;What could be more important than nice fat variable names that mean what they represent? It's the lowest common denominator in the world of understandable code.We are still coding in a modified version of Series/1 assembler from back in the 80's. Don't ask me why, but we do. It blows. We also have C+ and VB apps, but it's not all migrating to something modern yet. :sigh:
John Cardinal wrote:
What could be more important than nice fat variable names that mean what they represent?
I appreciate that everytime I load up VS. BW
If you're not part of the solution, you're part of the precipitate.
-- Steven Wright