The joys of doing Documentation
-
So here i am with my task (if you can say that) to do a documentation on 2 of the projects. And while doing it i saw a just brilliant piece of code. For my defense i will say its not mine.
try
{
//just some code
}
catch (Exception ex)
{
throw ex;
}So what's your memories of your first documentation? I guess i will have what to tell about mine :)
Microsoft ... the only place where VARIANT_TRUE != true
You know, that's not so bad if there was just on little change. Handle the exception. As for first retro-documentation my fav was working on a project and for some fupped reasoning we sold the source code. The PHB said that all modules had to be commented with file headers stating the author. When we came across anything that was [0] of unknown origin or [b] too embarrassing to admit to, we used one of the SysAdmins' names. :-D
-
So here i am with my task (if you can say that) to do a documentation on 2 of the projects. And while doing it i saw a just brilliant piece of code. For my defense i will say its not mine.
try
{
//just some code
}
catch (Exception ex)
{
throw ex;
}So what's your memories of your first documentation? I guess i will have what to tell about mine :)
Microsoft ... the only place where VARIANT_TRUE != true
That's called the Try-Catch-Throw pattern. It is thoroughly described in
Real World Programming Patterns by W.T. and F.
-
That's called the Try-Catch-Throw pattern. It is thoroughly described in
Real World Programming Patterns by W.T. and F.
Maybe i should have added that this function is actually exported from the dll and used in another dll. The main purpose was reading a xml file. I don't see any point of using try catch with a throw in the first place and this function isn't safe, because when i use it from the other dll for some trivial job as xml reading I assume that the errors are properly treated in it and I would not use try catch, meaning automatically an crash with invalid xml which i expirienced. For me this function is useless when i can just write that code myself.
Microsoft ... the only place where VARIANT_TRUE != true
-
You know, that's not so bad if there was just on little change. Handle the exception. As for first retro-documentation my fav was working on a project and for some fupped reasoning we sold the source code. The PHB said that all modules had to be commented with file headers stating the author. When we came across anything that was [0] of unknown origin or [b] too embarrassing to admit to, we used one of the SysAdmins' names. :-D
Nagy Vilmos wrote:
When we came across anything that was [0] of unknown origin or [b] too embarrassing to admit to, we used one of the SysAdmins' names. :-D
Quite interesting numbering scheme. Was documentation created from the project organized similarily? :-D
The good thing about pessimism is, that you are always either right or pleasently surprised.
-
Nagy Vilmos wrote:
When we came across anything that was [0] of unknown origin or [b] too embarrassing to admit to, we used one of the SysAdmins' names. :-D
Quite interesting numbering scheme. Was documentation created from the project organized similarily? :-D
The good thing about pessimism is, that you are always either right or pleasently surprised.
[a] Considering how long you've been and [ii] that you read a lot of forum posts I'd assume you [3] know the convention.
-
Maybe i should have added that this function is actually exported from the dll and used in another dll. The main purpose was reading a xml file. I don't see any point of using try catch with a throw in the first place and this function isn't safe, because when i use it from the other dll for some trivial job as xml reading I assume that the errors are properly treated in it and I would not use try catch, meaning automatically an crash with invalid xml which i expirienced. For me this function is useless when i can just write that code myself.
Microsoft ... the only place where VARIANT_TRUE != true
Didn't you see the joke in my post? Look at the author's name of the (non-existing) "book" I quoted. The code snippet you showed us is a WTF, isn't it?
-
Didn't you see the joke in my post? Look at the author's name of the (non-existing) "book" I quoted. The code snippet you showed us is a WTF, isn't it?
-
Maybe i should have added that this function is actually exported from the dll and used in another dll. The main purpose was reading a xml file. I don't see any point of using try catch with a throw in the first place and this function isn't safe, because when i use it from the other dll for some trivial job as xml reading I assume that the errors are properly treated in it and I would not use try catch, meaning automatically an crash with invalid xml which i expirienced. For me this function is useless when i can just write that code myself.
Microsoft ... the only place where VARIANT_TRUE != true
Argonia wrote:
I don't see any point of using try catch with a throw in the first place
I do. Imagine a pretty red dot on the left margin. Every time this code fails the breakpoint is hit and you can see what exception will be thrown to the rest of the code, especially when it is called from many places. You can find this in "Real World Programming Patterns", chapter IV: "Abuse of debugger". ;)
-
So here i am with my task (if you can say that) to do a documentation on 2 of the projects. And while doing it i saw a just brilliant piece of code. For my defense i will say its not mine.
try
{
//just some code
}
catch (Exception ex)
{
throw ex;
}So what's your memories of your first documentation? I guess i will have what to tell about mine :)
Microsoft ... the only place where VARIANT_TRUE != true
We don't need no stinking documentation...the code is the documentation. :laugh: Code documentation done after the fact is probably worse than having to create a user manual! X| Even worse is documenting someone else's code!
"Go forth into the source" - Neal Morse
-
You know, that's not so bad if there was just on little change. Handle the exception. As for first retro-documentation my fav was working on a project and for some fupped reasoning we sold the source code. The PHB said that all modules had to be commented with file headers stating the author. When we came across anything that was [0] of unknown origin or [b] too embarrassing to admit to, we used one of the SysAdmins' names. :-D
Or at least at least AT LEAST! do use
{
throw;
}to prevent slicing of the exception type. (But maybe that's the purpose: outside code can't handle some Exception-.derived exception)
-
So here i am with my task (if you can say that) to do a documentation on 2 of the projects. And while doing it i saw a just brilliant piece of code. For my defense i will say its not mine.
try
{
//just some code
}
catch (Exception ex)
{
throw ex;
}So what's your memories of your first documentation? I guess i will have what to tell about mine :)
Microsoft ... the only place where VARIANT_TRUE != true
I clearly remember coming across a comment in the source of an old product called C-Scape. (That was a common meme back then: C-Scape, C-Front, C-Shell, etc. How I laughed.)
/**
* A squid eating dough in a polyethylene bag is vast and bulbous, got me.
**/"If you don't fail at least 90 percent of the time, you're not aiming high enough." Alan Kay.
-
So here i am with my task (if you can say that) to do a documentation on 2 of the projects. And while doing it i saw a just brilliant piece of code. For my defense i will say its not mine.
try
{
//just some code
}
catch (Exception ex)
{
throw ex;
}So what's your memories of your first documentation? I guess i will have what to tell about mine :)
Microsoft ... the only place where VARIANT_TRUE != true
I must say I see this exact kind of foolishness pretty often, in the questions at the Q&A forum.
—SA
Sergey A Kryukov