Petko --I don't think I'm going to change your mind or development methods, but I wanted to put in my two cents.
It's good that most code-related documentation does ship with the code (although as Oliver has pointed out -- some of it is in the Cookbook, which does not). However, that's still external documentation, and nowhere near self-documenting code -- and the introduction semantic names for variables or methods is a common refactoring. It's certainly not obvious staring at php code that the lookup-table is over in the wiki.d folder. If the code is confusing to you, the lead developer -- just think how it looks to outsiders who would like to contribute to the project, but are left staring at a codebase that seems more akin to a DSL. This is not meant as an attack -- you and Pm (and others, but you two as lead and originator) have done an incredible job. I want to contribute, and if there is some way I can help with the problems I've raised, please let me know. How can one contribute to the code? I'm not finding it quickly on the wiki -- the contributors page lists contributors, but not how to do it: http://www.pmwiki.org/wiki/PmWiki/Contributors The SVN page only discusses how to pull the code, not to offer changes: http://www.pmwiki.org/wiki/PmWiki/Subversion -Michael Paulukonis http://www.xradiograph.com <http://goog_2112721603>Interference Patterns (a blog)<http://www.xradiograph.com%5Cinterference> @XraysMonaLisa <https://twitter.com/XraysMonaLisa> http://michaelpaulukonis.com <http://www.BestAndroidResources.com> Sent from somewhere in the Cloud (hearthrug, by the fender) On Fri, Feb 7, 2014 at 8:36 PM, Petko Yotov <5...@5ko.fr> wrote: > michael paulukonis writes: > >> If brevity is needed for performance reasons, can't the source be run >> through a minifier prior to packaging? >> > > Some brevity is needed to me in order to keep my sanity and to be > efficient. That includes writing less code, making less errors and seeing > more of the program logic at once on my screen. > > When some helper functions are used tens or hundreds of times, it helps > having short function names - abbreviations of the intended functionnality. > I also feel that it is much easier to remember what the function does, > compared to, for example, the order of its arguments (that's why I like > most functions with a single argument :-). > > Also, these are just helper functions: they do some things that are > required to be done, but are not essential to the grand program logic, and > I want them out of my way. > > > A program IS NOT communication between a human and the machine. >> It's a communication between a developer and the next developer. >> > > It is also a communication between a developer and himself/herself. > > > The communication I receive from a function names like "PCCFR" or "XLSDV" >> or "PZZ" is "you are not worthy of contributing to this codebase until you >> memorize our secret language [hint: it only _looks_ like PHP]." >> > > I'm willing to better document these functions if the current > documentation is insufficient. > > There is absolutely no requirement for a developer to use these functions. > A module can contain all necessary code without using any of the above or > other core helper functions. > > For example, PHP has more than one way to define callback functions; ours > PCCF() "PmWiki Create Callback Function" is tested and works with PHP 4.2 > to 5.5 but you are not required to use it. > > Other example: you can escape some HTML entities in different ways; ours > PHSC() "PmWiki HTML Special Chars" is tested and works with PHP 4.2 to 5.5, > even when your text stream contains invalid characters for the default > encoding, which changes in different PHP versions. But you are not required > to use it: if you like, you can write your own functions, debug them and > support them for your users. :-) > > > Petko > > > [Petko, maybe you were making a joke by taking something to an extreme.] >> >> > On Fri, Feb 7, 2014 at 12:31 PM, Petko Yotov <<URL:mailto:5...@5ko.fr>5ko@ >> 5ko.fr> wrote: >> >> Instead of PCCF('function code', 'r'), I'd prefer writing simply >> PCCFR('function code'). >> >> (... PmWiki Create Callback Function Return...) >> >> Petko >> > > > _______________________________________________ > pmwiki-users mailing list > pmwiki-users@pmichaud.com > http://www.pmichaud.com/mailman/listinfo/pmwiki-users >
_______________________________________________ pmwiki-users mailing list pmwiki-users@pmichaud.com http://www.pmichaud.com/mailman/listinfo/pmwiki-users
