I have just noticed this thread resurfacing, in the meantime few new functions were added to help with function definitions:

• WithCleanup, a documented version of WithLocalSettings
• The new Enclose/Confirm family
• ArgumentsOptions, a documented version of Arguments and ArgumentsWithRules

Spending few minutes with those I could write a version of movingAverage that is only using documented code

ClearAll[movingAverage]

movingAverage::usage = 
"movingAverage[vec$, n$] computes the moving average of the numerical vector vec$ \
by taking the mean of subsets of length n$.";
movingAverage::numinv = "Expecting a rectangular array of length greater than \
or equal to `2` instead of `1`.";
movingAverage::sizeinv = "Expecting a positive integer instead of `1`.";

$LSH : movingAverage[___] :=
Module[
	{res},
	res = Enclose @ Module[
		{args, opts, vec, n},
		{args, opts} = Confirm @ ArgumentsOptions[$LSH, 2];
		n = ConfirmBy[args[[2]], IntegerQ[#] && # > 0 &, Message[movingAverage::sizeinv, args[[2]]]];
		vec = ConfirmBy[args[[1]], ArrayQ[#] && Length[#] > n - 1 &, Message[movingAverage::numinv, args[[1]], n - 1]];
		Mean[Transpose[Partition[vec, n, 1]]]
	];
	res /; !FailureQ[res]
]

The code can be further simplified if one is happy to return a Failure expression instead of the unevaluated one.

I have attached two files that might be considered a partial answer to this question.

One is "template for Package". This is a slightly changed version of Maeder's original suggestion for Mathematica package format, to include documentation and a layout that facilitates code maintenance and code readability. A full reference to Maeder' work appears in this file.

The other is template for function.nb. This is derivative of Maeder's format, intended to facilitate code curation, code maintenance, and code validation after Mathematica version changes.

Please feel free to change and improve these files. As an example of a needed change, template for Package.nb contains none of Mathematica's automated test functions. Since the skeleton of "templateForPackageV0R0.nb" dates back a bit, perhaps it is time to incorporate Wolfram functions and practices introduced since then.

Attachments:

This is a general framework that can be used to define any production level function.

I am going to use the ThrowFailure mechanism and the SetUsage function so I need GeneralUtilities`

Needs["GeneralUtilities`"]

First thing: documentation!

SetUsage[movingAverage,
"
movingAverage[vec$, n$] computes the moving average of the numerical vector vec$ \
by taking the mean of subsets of length n$.
"
];

The function may need options, we define them here and sort them properly

Options[movingAverage] = {

} // SortBy[ToString @* First];

Some internal options that we may not want to expose can go here

movingAverageOptions = {

} // SortBy[ToString @* First];

The main entry point for our function. This will do basic argument parsing and counting (no validation) and return either the result or unevaluated depending on the input or the execution. The key piece here is Arguments: it returns a list with two sub-list (or whatever you specify in the optional third argument), one for the arguments and one for the options. Arguments are counted and the proper message is issued, options are verified against Options[] and an optional list in the fourth argument. If some arguments are expected to be rules, use ArgumentsWithRules.

movingAverage[args___] :=
Module[{a, res},
    a = System`Private`Arguments[movingAverage[args], 2, List, movingAverageOptions];
    res /; a =!= {} && !FailureQ[res = imovingAverage @@ a]
]

Now the main code for the function. I tend to define a getOption utility not to have to write that longish piece of code over and over.

imovingAverage[args_, opts_] :=
CatchFailureAsMessage[movingAverage,
Module[
    {getOption, vec, n},

    getOption[name_] := OptionValue[{movingAverage, movingAverageOptions}, opts, name];

    n = argumentTest["PositiveInteger", "sizeinv"][args[[2]]];
    vec = argumentTest[{"NumericList", n}, "numinv"][args[[1]]];

    Mean[Transpose[Partition[vec, n, 1]]]

]]

Argument validation can be done in countless ways, here's a sub-values based one I just came up with. It can be saved in a separate file (Common.wl, Test.wl, ...) to be used in many places. If the tests are standard one can probably avoid passing the message name.

argumentTest["PositiveInteger", message_] := 
Function[
    If[Internal`PositiveIntegerQ[#],
       #,
       ThrowFailure[message, #]
    ]
]

argumentTest[{"NumericList", n_Integer}, message_] := 
Function[
    If[VectorQ[#, Internal`RealValuedNumericQ] && Length[#] >= n,
       #,
       ThrowFailure[message, #, n]
    ]
]

And now the messages. For these kind of standard tests, one can define General messages that can be used with any head.

movingAverage::numinv = "Expecting a list of numerical quantities of length greater of equal then `2` instead of `1`.";
movingAverage::sizeinv = "Expecting a positive integer instead of `1`.";

Not so easy to find the documentation for @*. I found it on the Documentation Center page tutorial/OperatorInputForms, where it says that @* is a special form for Composition (q.v.).

Then SortBy[ToString@*Last] is a shorthand for SortBy[Composition[ToString, Last]].

Why you expect that string are sorted the same way as numbers?

In[813]:= Sort[{3, 10, 20}]

Out[813]= {3, 10, 20}

In[814]:= Sort[ToString /@ {3, 10, 20}]

Out[814]= {"10", "20", "3"}

I think this is a standard ordering for strings, unless you pad them with zeros on the left to match the length

In[815]:= Sort[IntegerString[#, 10, 2] & /@ {3, 10, 20}]

Out[815]= {"03", "10", "20"}

I am not using KeySort as it produces an association.

There are no secret advantages, just a misunderstanding. Indeed I am not sorting by Last but by First (see my post).

I thought you where asking a general question about the sorting algorithms.

Not dismissing your methods, but there are easier and cleaner ways. If you define with multiple definitions with different argument types for patterns or with trailing arguments which are not rules you can set messages appropriate for each bad input. Either way with messages or your advanced error checking you're still writing more code.

@Giulio, I don't know how I missed this when you originally posted it. Thanks for this post.

One thing I observe here is the heavy reliance on internal and undocumented functionality. I mentioned before how this is basically unavoidable for package development (think e.g. Internal`WithLocalSettings).

There's GeneralUtilities, System`Private`Arguments, several Internal` context functions for verifying types, etc.

Since these are not documented, they are hard to discover. If I do discover them, I cannot be sure about how to use them. If I do use them, and they break, I can't get support, and my bug report might be rejected (so why even bother sending it?)

Of course, I still do use some of these because they are essential to package development. But the situation demonstrates well how WRI basically ignores (potential) package developers. There are very few quality packages that do not come fro WRI directly, and this is surely the main reason.

Another thing I observe is that you construct several layers around the basic function. How will this affect performance? This function may later be used to implement other functions, which are then used to implement yet other functions, and all this checking overhead adds up. Paying attention to the error checking overhead is a critical aspect of package development.

I notice that you use VectorQ[..., Internal`RealValuedNumericQ]. What you did not mention that this is basically the only right way to check if the input is a real vector because it won't unnecessarily check every element of packed arrays, and thus will perform very well.

In[371]:= arr = RandomReal[1, 1000000];

In[372]:= VectorQ[arr, Internal`RealValuedNumericQ] // RepeatedTiming
Out[372]= {2.4*10^-7, True}

In[373]:= MatchQ[arr, {___?Internal`RealValuedNumericQ}] // RepeatedTiming
Out[373]= {0.15, True}

I'm not aware of this being documented anywhere in spite of how important it is—another example of how support for package developers is lacking.

Because these things are not documented, they are also more likely to be buggy (since they're not used by as many people). Example: in M10.3 and before (if I recall correctly) VectorQ[{}, Developer`MachineIntegerQ] returns False.

The point I am trying to make is this:

1. If Mathematica is to stay relevant, there must be a vibrant package ecosystem

2. Support for package development and package developers is currently next to non-existent. We are forced to use internal unsupported functions whose use is either reverse engineered by the community or "leaked" by developers (like you did here). As a consequence, there are few Mathematica packages and many are not of high quality.

3. Functions that are not important for interactive use but critical for package development should be documented. There should be guides and tutorials on how to solve the basic problems that come up during package development. If there are standard solutions for the most common tasks, and both internal functions and third-party developers use these solutions, then we will see fewer bugs and better performance (both in Mathematica and in third-party packages).

4. Finally, quality packages should be highlighted and promoted by WRI themselves, both as an example of a healthy package ecosystem and as an example for future package developers to follow. I am not saying this because I develop packages, but because I believe it is critical for the health of Mathematica, a system in which I invested heavily.

I am going to keep posting here as I explore this topic.

One useful built-in function seems to be ArgumentCountQ. Check what it does using ?ArgumentCountQ. Here's an example:

In[16]:= ArgumentCountQ[f, 3, 1, 2]

During evaluation of In[16]:= f::argt: f called with 3 arguments; 1 or 2 arguments are expected.

Out[16]= False

It returns a boolean value indicating whether the argument count is correct. If it is not, it also issues a correctly formatted and informative message.

One problem with this function is that it does not count arguments on its own. Counting them is not as trivial as a Length: when there are options present, we would not usually want to include these in the argument count. It is also somewhat unclear what should be considered an option, and what should be considered an argument that is a Rule (e.g. as in Replace).

The Developer`CheckArgumentCount function solves this. For example,

In[17]:= Developer`CheckArgumentCount[f[1, foo -> 2], 1, 1]

During evaluation of In[17]:= f::argx: f called with 2 arguments; 1 argument is expected.

Out[17]= False

In[18]:= Options[f] = {foo -> Automatic};
Developer`CheckArgumentCount[f[1, foo -> 2], 1, 1]

Out[19]= True

Since both of these functions return True/False, they can be used in Condition to easily report errors while keeping the input unevaluated.