Wiktionary talk:Coding conventions

Some reservations

While I do agree that conventions are good, there are some that I don't agree with:

• Not exported functions should be declared with the local function construct. Why?
• When feasible, functions should be written to be callable both from templates and directly from other Lua functions, without creating a frame (or a table imitating one). This is not the practice that several of our most-used modules use. Instead, they have a submodule that acts as the template interface.
• Words in variable and function names should be separated with underscores. It seems that methods of objects have been named using camelcase, as in Module:languages for example. This was done after discussion.
• Placement of curly brackets should follow the K&R style. I think placing the opening bracket on the new line in all cases is more consistent than doing it only sometimes. It makes it less likely that editors not familiar with K&R style will apply it inconsistently.

—CodeCat 19:37, 29 July 2014 (UTC)

One by one:

• Because otherwise functions become global variables (unless the identifier has been explicitly declared as local in a parent scope, which might be even worse). You may inadvertently use a function from a module which you previously require()d, for one. Avoiding globals helps make relations between pieces of code explicit. I even thought about introducing w:Module:no globals here.
• Perhaps we can document this practice too.
• Ditto. Though I guess I do not have to repeat my opinion about introducing those classes.
• By "K&R style" I meant always put the brace on the same line as the control structure (which does not seem to have a name in w:Indent style, but K&R is the closest thing), so no discrepancy here. I remember Crockford doing a talk (I do not remember where it was, though) where he explained how this style helps avoid bugs caused by automatic semicolon insertion. (Maybe I should call it "Crockford style", since he recommends it in his own style guide.)

— Keφr 19:57, 29 July 2014 (UTC)

I always code in what the page calls "Allman style". By and large our template code is formatted in this style already. —CodeCat 20:04, 29 July 2014 (UTC)

Used to follow Allman too, but I switched to this "no-exceptions" variant of K&R and never looked back. As for templates, I think it makes rather little sense to compare template syntax with C-like languages, but I think my template indentation style can be described as similar to what the article calls banner style or Ratliff style (and sometimes even Lisp). Though I never treat coding style religiously; as long as it is readable, relatively consistent and not visually jarring, I am fine with it. — Keφr 21:02, 29 July 2014 (UTC)

The downside of declaring functions local is that you can't put them in any order anymore. So what if we adopt the practice of declaring two tables at the top, one for exported things and one for local things? Then you can prefix local function names with the name of that table, and the order of declaration is no longer restricted. —CodeCat 20:30, 27 August 2014 (UTC)

Accessing a local variable is faster than looking up a key in a table (which you also do when referencing a global; the table's name is _G). Also, putting everything in a local table variable would mean more typing. Moving functions around to make things work is a minor one-time inconvenience. Also, if you are reading code and find a function or variable whose definition you do not remember, knowing you can scroll up to find it (instead of down) is quite helpful. I get somewhat irritated when I read code and this assumption turns out to be incorrect. — Keφr 12:48, 29 August 2014 (UTC)

"Headword-line templates should either be implemented in a separate module using Module:headword, or use {{head}}."

Why so?

The reason I'm asking is that I would like to edit template:da-verb to include three more forms, and I would use parser functions "#if:" and "ifeq:"; thus, I presume I would need to use {{!}} instead of | somewhere. However, I can't seem to figure out how. This entire problem would be eliminated if I could just write the template from scratch, as I did with Template:da-adj before finding this page; so why use {{head}}?

I wrote the above; appearantly my browser logged out at some point.__Gamren (talk) 15:00, 2 August 2015 (UTC)

I don't think {{da-verb}} should have anymore forms. It's rather long already. If you want to include more forms, then I think it's time to make a separate inflection table template.

In any case, I've rewritten {{da-verb}} and {{da-adj}} to use {{head}}. —CodeCat 15:16, 2 August 2015 (UTC)

As clumsy as I find inflection tables, you're probably right; longer words would take up two lines. And thanks for fixing those.
I still don't get why we must call {{head}}, but whatever.__Gamren (talk) 13:17, 5 August 2015 (UTC)

Because {{head}} includes all kinds of extra (hidden) tags and applies special tricks that a plainly implemented template won't do. This is also why {{l}} and {{m}} should be used instead of plain links. Furthermore, if the format of {{head}} is ever changed, it will automatically change all templates that use it. It would become a maintenance nightmare if every template had to be edited separately.

As for the length, keep in mind that users may be viewing Wiktionary on rather small screens. It looks ugly when the headword line has to wrap around. —CodeCat 14:32, 5 August 2015 (UTC)

Reference templates - examples?

I've added some reference templates in recent years, but looking at this it seems that the names for these should include a language code. It would help to see an example markup on the page. (Are those at Category:Armenian reference templates well formed?) --A12n (talk) 15:01, 22 June 2019 (UTC)

@A12n: Whether names for reference templates should include a language code is up for a vote right now: see Wiktionary:Votes/2019-06/Language code into reference template names. I looked at several of the the Armenian reference templates and they seem to have good coding style, though honestly the HTML comments aren't really needed most of the time. — Eru·tuon 17:33, 22 June 2019 (UTC)

@Erutuon: Belated thanks for this info. Will consult the vote page.--A12n (talk) 16:11, 27 June 2019 (UTC)

Questions about Lua conventions

Some of these things seems really wrong:

1. "No exported functions should be declared with the local function construct."
2. "Alternatively, you may designate a separate function or module for functions callable from templates. By convention, this is done by creating a submodule named /templates."

The first item is confusing and is not really a coding convention so much as a restriction since it does not tell the reader what should be done. If it wasn't followed up immediately by "Global variables should not be used." it almost sounds as if one should use a global declaration. I really do not see an issue with code like:

local function xyzzy()
end
return {export=xyzzy}

so is this saying I should use a construct like:

local xyzzy = function()
end
return {export=xyzzy}

or

return {
	export = function()
	end
}

instead?

As for the second item, are we really asking people to develop separate subpage modules strictly for #invoke? Is this /templates construct supposed to require[[Module:basename]] for the API code and then be used like {{#invoke:basename/templates|function|...}} or just copy all the functionality? Either way this seems verbose, fragile and a maintenance nightmare. I think I would rather do something like:

if not ... then
	local api = require(mw.getCurrentFrame():getTitle())
	local mt = {}
	function mt:__index(k)
		local apival = api[k]
		if "function" ~= type(apival) then
			return apival
		end
		return function(frame)
			return apival(frame.args)
		end
	end
	return setmetatable({}, mt)
end
local p = {}
function p.xyzzy(args)
end
return p

Is it me or do these "conventions" seem arbitrary and in need of some serious work? —Uzume (talk) 06:00, 24 April 2024 (UTC)