 |
|
|
|
|
|
| |
| |
|
|
|
|
| |
| |
|
|
clipka wrote:
> Docman? Javadoc?
To clarify, I'm thinking maybe something more along the lines of the
BON<->Eiffel equivalence, where something that looks like UML can be turned
into source code and back again with the appropriate tool.
Something beyond the name of the function and the types of its arguments.
Plus, documentation that covers something besides the individual functions
to be called, that covers what you cannot for now deduce from the source
code itself.
I know javadoc (and similar) is supposed to cover that. In practice, it
gives you a place to write that stuff down, but does nothing to make it
useful to the author to do so. So documentation even of that type becomes a
cost rather than a benefit.
How many projects have you seen with the doxygen or javadoc or whatever have
either obvious cut-and-paste errors or no documentation beyond what you can
gleen from the source at all?
--
Darren New, San Diego CA, USA (PST)
I ordered stamps from Zazzle that read "Place Stamp Here".
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Darren New schrieb:
> clipka wrote:
>> Docman? Javadoc?
>
> Were that helpful, it might fit the bill. :-) As it stands now, it
> seems more often an excuse to not write documentation than a tool for
> writing it.
That's not a problem of the tool, but the person using it. Those people
taking it as an excuse wouldn't do any docuentation at all otherwise,
unless forced at gunpoint.
As far as making life easier for people who do have the honest desire to
document properly, I think integrating the documentation with the source
code is a good way to go, and docman and javadoc make good tools for hem.
Then again, maybe it's the approach taken from the wrong side, and the
true proper way would be embedding the source code in the documentation,
not vice versa - if only for the psychological effect.
>> > To avoid security problems?
>> I guess this would require a proper definition of "security problems".
>
> Code doing things the author didn't want it to do because malicious
> people intentionally caused it to happen.
There's no general way around it, because malicious people of this type
are highly intelligent and inventive. Whatever you'd integrate into the
language itself would just give you a /false sense of/ security.
The only truly safe computer system would be an isolated computer locked
in a stainless steel safe, with the key thrown into the Atlantic, and
the safe sunk in the Pacific. Which would somewhat limit its usefulness
I guess :-P
The only thing you can do about it is /defensive/ programming - but
that's a paradigm you probably cannot support with language features I
guess. Well, maybe stuff designed for contract-oriented programming
would help with this.
> Stuff like the ability for me to know that my change hurt your code.
> Something like unit testing, only built into the language, say.
That seems to go into a similar direction as contract-oriented design.
>> But it appears to me that as far as libraries are concerned, OOP has
>> been a tremendous success regarding code re-use.
>
> Ehn, to some extent. How many of the libraries you use would work just
> as well without OO, or with faked OO (like C's stdio fakes OO)?
It's not a question of how well they would work - it's a question of how
easy they were to implement, and how easy they are to use.
Try implementing and using generic container classes in a non-OO language.
Then try to refactor your application to use a deque container instead
of a stack for a certain job. Or a tree-backed map instead of a
hash-table-backed one someplace else.
You won't have much success without implementing verbosely what OO
languages do for you behind the scenes.
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
clipka wrote:
> That's not a problem of the tool, but the person using it. Those people
> taking it as an excuse wouldn't do any docuentation at all otherwise,
> unless forced at gunpoint.
Not necessarily. As I said elsewhere, a tool that would make the high-level
documentation generate source code (and where the changes to the source code
would be reflected in the HDL) would help. It would let people who are
designing the system document it as part of the progress forward.
The problem with writing code documentation is that it doesn't help the
coder. It only helps the people who come after. So it's seen as a waste
unless the coder understands the business reason for it.
Imagine something like TDD, except with documentation instead of tests.
Or imagine a block diagram with arrows showing data flow between the blocks,
where that's *actually* the code.
> As far as making life easier for people who do have the honest desire to
> document properly, I think integrating the documentation with the source
> code is a good way to go, and docman and javadoc make good tools for hem.
If you're documenting the *code*, yes. I'm wondering if it's also possible
to design a language that makes it easy to document the intention, the
architecture, etc as part of building the code. Tangle and weave, anyone?
> Then again, maybe it's the approach taken from the wrong side, and the
> true proper way would be embedding the source code in the documentation,
> not vice versa - if only for the psychological effect.
Yes, exactly something like this. We probably won't get there as long as
the primary form of source code is ascii strings.
> There's no general way around it, because malicious people of this type
> are highly intelligent and inventive. Whatever you'd integrate into the
> language itself would just give you a /false sense of/ security.
Hard to say. Certainly having a language with bounds checking is safer than
a language without bounds checking. How far can that go?
> The only thing you can do about it is /defensive/ programming - but
> that's a paradigm you probably cannot support with language features I
> guess. Well, maybe stuff designed for contract-oriented programming
> would help with this.
Yeah, that's the sort of thing I'm thinking. Or like the C part of ACID.
>> Stuff like the ability for me to know that my change hurt your code.
>> Something like unit testing, only built into the language, say.
>
> That seems to go into a similar direction as contract-oriented design.
To some extent, yes. That, or typestate analysis, or some such. I don't know
the answer. I just know it's a problem looking for a better answer.
> Try implementing and using generic container classes in a non-OO language.
> Then try to refactor your application to use a deque container instead
> of a stack for a certain job. Or a tree-backed map instead of a
> hash-table-backed one someplace else.
I can't imagine changing a queue to a stack without needing to rewrite a
fair amount of the code using that structure.
C++ seems to do pretty well, and its not using any OO for the STL. Python
and LISP also do pretty well without actually using the OO portions of the
language, as would Ada I think. Erlang (and Hermes) both handle this just
fine as well, and that's not OO. You just need good encapsulation, not
inheritance or dynamic binding or anything like that.
> You won't have much success without implementing verbosely what OO
> languages do for you behind the scenes.
Sure. OO is pretty good at data structures and GUIs. But what about other
libraries? What about math libraries, HTTP libraries, networking libraries,
databases, etc? None of those types of libraries tend to be designed for you
to subclass the instances.
--
Darren New, San Diego CA, USA (PST)
I ordered stamps from Zazzle that read "Place Stamp Here".
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Well now, there are basically two ways to do documentation:
>
> You already lost. If you're not documenting things that have no place in
> the source code to put the documentation, you've already failed at
> documenting your system.
That too.
I'm thinking about documenting a library API, but if you wrote an
application and want to write a user manual for it... the user isn't
going to give a damn about why you have to register a callback after
creating a button.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Method #2 suffers from the problem that there's so much chatter in the
>> source file that you can't actually find the executable code any more.
>> It makes small, simple modules look huge and complex.
>>
> My experience is that that's not the case.
>
> To the contrary: Breaking up the source code with commenting blocks
> helps give the code more structure, even if you don't change a single
> statement.
You'd *think* it would help, but in general it just gets in the way.
When you're trying to edit the documentation, there's all these lumps of
code in the way, and when you're trying to edit the code, there's chunks
of documentation in the way. (Plus, in Haskell in particular, the
documentation tends to be vastly longer than the code.)
> In any case I guess we agree that the problem of documentation needs to
> be addressed not by programming /languages/, but by programming
> /environments/.
Yeah, pretty much. (The documentation is usually comments, after all.
All languages support this.)
> I guess the ideal solution would be an IDE that is capable of managing
> hypertextual RTF documents alongside with code, highly integrated with
> the version management software, and for each change would ask: "What
> was the nature of your code change, Dave?" - being smart enough to
> identify which functions were actually changed, and also which ones
> might be affected indirectly.
Yeah, that sounds about right. Something like Google's SideWiki.
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>>> > To avoid security problems?
>>> I guess this would require a proper definition of "security problems".
>>
>> Code doing things the author didn't want it to do because malicious
>> people intentionally caused it to happen.
>
> There's no general way around it, because malicious people of this type
> are highly intelligent and inventive. Whatever you'd integrate into the
> language itself would just give you a /false sense of/ security.
As far as I can tell, 98% of all security issues are buffer overruns -
trivially fixable, yet nobody seems to think it's necessary.
Then there are things like data tainting (which could be enforcible at
compile-time with no run-time overhead). Hell, in Haskell land, people
regularly attempt to write code which is *provably secure*. (But then,
you have to define "secure" first... It's easy to prevent buffer
overruns, but not so simple to prevent glitches where access denied
messages inadvertantly reveal information indirectly.)
>> Stuff like the ability for me to know that my change hurt your code.
>> Something like unit testing, only built into the language, say.
>
> That seems to go into a similar direction as contract-oriented design.
Yeah, that's a nice idea. Doesn't seem very popular though...
> Try implementing and using generic container classes in a non-OO language.
>
> Then try to refactor your application to use a deque container instead
> of a stack for a certain job. Or a tree-backed map instead of a
> hash-table-backed one someplace else.
>
> You won't have much success without implementing verbosely what OO
> languages do for you behind the scenes.
Tried using Haskell recently? Haskell is not OO.
Sure, you need encapsulation, and you need polymorphism. You also need
dynamic binding *if* you want to change your mind about which data
structure you're going to use *at run-time*. But you don't necessarily
need implementation inheritance, or mutable state for that matter...
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
>> Aren't computers supposed to "program themselves" by now? Anyone
>> remember that one?
>
> Well, in a way they do: Think about code optimization.
>
> The only illusion was about the level of abstraction that could be
> obtained. I guess the problem there is that natural human language is
> ill-suited for specifying even the problem to be solved with a computer
> program (let alone the algorithm to solve it): As soon as precision is
> required (and with computers that's obviously the case), it quickly gets
> overly verbose and cumbersome (every scientific paper gives testimony of
> this fact).
I think what happened is that somebody invented Prolog, and it makes it
almost seem like the computer is "thinking". It lets the computer solve
logical problems as if by magic (i.e., it doesn't look like a regular
algorithm, it looks like real insight). And people thought that in a few
years' time, somebody would come up with a set of predicates to describe
the operation of a computer program, you'd put in a mathematical
description of what the program is supposed to do, and Prolog would
magically compute the most efficient sequence of machine instructions...
...which would just mean writing programs as mathematical statements
rather than lists of instructions. It would just be another programming
language. And, you know, people have argued that programming in Haskell
is like programming with mathematics, so...
[One might also mention Mathematica.]
--
http://blog.orphi.me.uk/
http://www.zazzle.com/MathematicalOrchid*
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Orchid XP v8 a écrit :
> mathematical description of what the program is supposed to do
Ahahah. even the simple "description of what the program is supposed to
do" is usually a long painful phase between the requester and the
programmer.
Users do not know what they want. When they do, they usualy fail to
express it. And should it happened, there would be some misunderstanding
at some stage.
Remember, the "What" is not only the purpose, but also often the how.
and the devil is in the details.
"I want a raytracer..." is not a specification. Too ambiguous.
I want the program to output "Hello, world!", now, that's enough.
And for the nice one: "I want a proof of the Fermat..."
--
A: Because it messes up the order in which people normally read text.<br/>
Q: Why is it such a bad thing?<br/>
A: Top-posting.<br/>
Q: What is the most annoying thing on usenet and in e-mail?
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Orchid XP v8 wrote:
>>> Well now, there are basically two ways to do documentation:
>>
>> You already lost. If you're not documenting things that have no place
>> in the source code to put the documentation, you've already failed at
>> documenting your system.
>
> That too.
>
> I'm thinking about documenting a library API,
It's fine for the details. But try to document (say) the BSD interface to
TCP by documenting only the listen(), accept(), bind(), and connect() calls.
Without understanding what an IP address is, or a socket, or how DNS works,
etc you're still not going to win.
Or take something like a big windowing system, or a 3D graphics system, or a
physics library, and try to document *just* the routines without documenting
the architecture of the system. You'll spend three days trying to find out
where to start reading the documentation.
--
Darren New, San Diego CA, USA (PST)
I ordered stamps from Zazzle that read "Place Stamp Here".
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
| |
|
|
Orchid XP v8 wrote:
> As far as I can tell, 98% of all security issues are buffer overruns -
> trivially fixable, yet nobody seems to think it's necessary.
The three biggest are buffer overruns, SQL injection, and XSS injection.
--
Darren New, San Diego CA, USA (PST)
I ordered stamps from Zazzle that read "Place Stamp Here".
Post a reply to this message
|
|
| |
| |
|
|
|
|
| |
|
|
