[pmwiki-users] Proposed change to pmwiki.php: Markup_e

michael paulukonis xraysmalevich at gmail.com
Tue Feb 11 09:00:14 CST 2014


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 <5ko at 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:5ko at 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 at pmichaud.com
> http://www.pmichaud.com/mailman/listinfo/pmwiki-users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://www.pmichaud.com/pipermail/pmwiki-users/attachments/20140211/e0ca1271/attachment.html>


More information about the pmwiki-users mailing list