On 17/01/14 00:14, Marc Weber wrote:
I've started this wiki to document patches / efforts / idea to improve
the situation. I started by documenting why "vim sucks":
http://vim-wiki.mawercer.de/wiki/index.html
One of the main issues is:
- documenting source does not add value
- patching Vim would, but which is the best upstream for Vim?
Do we want to keep using C (I don't think so, because even Bram sayd
that coding higher level stuff in C is tough)
Ah, yes. Yet another Wiki has been set up as a not-very-well-disguised
attempt to surreptitiously coerce and control the future direction of
ViM down their own personal path. And this latest Wiki doesn't even try
to attempt to address the Original Poster's concern(s):
On 16/01/14 15:07, Tony wrote:
> I don't even know where to begin. And threads asking people to qualify
> what they probably *can't begin to articulate* because, *to fresh eyes*,
> I dare say, the code looks big. What does what? ... Centralized, Internal
> docs, even in a broad sense, would be tremendously constructive.
The crux is about internal documentation. Not "feature documentation",
which is what the online help system covers, not tools, not SCMs, not
about rewrites in C or C++, and it is definitely not about "why ViM
'sucks'".
It is about code documentation, of which ViM has *none*, which will enable
people to understand just what on earth is going on inside deep inside the
belly of ViM itself. We don't need another Wiki for this. We need people
who will put in hard graft to read the source code, understand it, and
describe it *in laymen terms* for others in simple text files that live
in the
source code control system itself, possibly alongside the very files they
are describing.
And this kind of documentation *does add value*. It is crucial in making
sure that a developer understands the context of any fix/enhancement
before attempting the fix. It ensures that any change has the highest
chance of working properly and integrating with surrounding sub-
systems with minimum breakage and/or regression, which increases final
acceptance probability and allows more good features to be integrated
(e.g. timers, background task queues, multiple language bindings, etc).
Bram and one or two others (e.g. Mr. Mechelynck) are currently the only
people with a good overall knowledge of the code base and this is not
good because (1) should Bram become "unavailable" for any reason, an
information vacuum would result causing chaos, and (2) the few people
with knowledge become a bottleneck for people without it wanting to ask
about how the system works.
For those who have worked on any properly organised project, Open
Source or not, having an overview of *how the code was designed*
and *how it works* is more important than just "understanding code".
For example, the Linux kernel, which I have developed and debugged
as part of my job, has a "readme.txt"-style file for every logical sub-
system. There is a dedicated documentation folder that houses most
of these files, while others reside in the directory where the code itself
is sitting. A read-me typically contains:
1) an overview of how code is executed from upper layers, how lower
layers are called, and a *logical* data-flow description (e.g. key strokes
are passed in via X and processed by Y", or "disk buffers come in
through x.c and are queued using y.c". References to code-level
structures are also made to familiarise the developer with the headers.
2) ASCII diagrams are included where necessary to describe, amongst
other things:
-> data layouts within important or often-used buffers.
-> flow chart logic of complicated functions.
3) Details of algorithms used, modifications to those algorithms to
handle certain non-standard corner cases in the sub-system's design,
and most importantly, why those algorithms were used in the first
place (execution and/or memory efficiency, platform constraints, etc).
And another thing. It's no good writing such documentation and then
leaving it to go out of date. It must be rigorously maintained and kept
up to date as every patch is developed and submitted.
I mentioned the Linux kernel as an example. This project is very easy
to work on and understand due to its level of descriptive detail about
design and logical operation, making it hugely popular with developers.
And you don't have to be a rocket scientist to understand what effect
this has had in contributing to the astonishing increases in functionality
and rates of global adoption of the kernel as a result.
--
--
You received this message from the "vim_dev" maillist.
Do not top-post! Type your reply below the text you are replying to.
For more information, visit http://www.vim.org/maillist.php
---
You received this message because you are subscribed to the Google Groups "vim_dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to vim_dev+unsubscr...@googlegroups.com.
For more options, visit https://groups.google.com/groups/opt_out.
