برنامه نویسی با سواد در Go

رویکرد «کد به‌عنوان ویکی» ما بسیار کمتر از استاندارد تعیین‌شده توسط دونالد کنوت است، اما امیدواریم که او آن را گامی در جهت درست ببیند.

در طول هکاتون اخیر شرکت، منشور تیم من بهبود مستندات برای Steampipe SDK بود< /a>. مانند سایر اجزای سیستم Steampipe، SDK افزونه در Go نوشته شده و در pkg.go.dev. نسخه ای که در زمان شروع ما وجود داشت اینجا است. همانطور که معمول است، مستندات یک کاتالوگ خودکار از توابع و انواع بود. برای توضیح نحوه استفاده از آن توابع و انواع، راهنمای را در سایت steampipe.io ارائه کردیم. .

چالش هکاتون ما این بود که چنین راهنمایی را در مستندات تولید شده ببافیم. اگر در حال نوشتن یک افزونه Steampipe هستید، لیست وظایف شما به این صورت است:

1. افزونه را تعریف کنید
2. نقطه ورودی افزونه را ایجاد کنید
3. اولین جدول خود را تعریف کنید
4. …

این کارها مستلزم استفاده از توابع و انواع هستند، اما در حالی که نظرات پیوست شده به آن توابع و انواع می‌توانند مستندات تولید شده را بهبود بخشند، اما برای نمایش سطح بالایی که ما هدف آن بودیم، بسیار جزئی هستند. در جستجوی الهام، توسعه‌دهنده اصلی Steampipe کای داگر متوجه شد که صفحه سطح بالای ما فاقد بخش نمای کلی است که در مستندات دیده است. برای pgx، یک درایور Go برای Postgres. p>

این نمای کلی از https://github.com/jackc/pgx/ می‌آید blob/master/doc.go، که یک نظر طولانی است (که از بروید نحو نظر استفاده می کند. a>) به دنبال آن یک اعلامیه بسته.

بنابراین ما یک doc.go اضافه کردیم سطح بالای مخزن ما برای ایجاد این نمای کلی.

نوشتن ویکی در نظرات Go

ما از نام doc.go استفاده کردیم زیرا به نظر متعارف است، اما می‌توانست آن را foo.go نامید. آنچه برجسته است این است که یک فایل Go معتبر است که به یک بسته تعلق دارد. بسته شامل هیچ کدی نیست، فقط مستندات. برای ایجاد بخش‌های نمای کلی، سرصفحه‌هایی نوشتیم، و در هر بخش وظایف یک افزونه‌نویس را با استفاده از روایت، مثال‌های کد درون‌خط، پیوندهای داخلی به توابع و انواع، و پیوندهای خارجی به نمونه‌های جاهای دیگر شرح دادیم.

قابلیت پیوند در فضای نام کد یک امر آشکار بود. برای توصیف کار به نام افزودن توابع هیدرات، به عنوان مثال، این را نوشتیم:

# Add hydrate functions

A column may be populated by a List or Get call. If a column requires data not provide by List 
or Get, it may define a [plugin.HydrateFunc] that makes an additional API call for each row.
Add a hydrate function for a column by setting [plugin.Column.Hydrate].

بخشی که توسط سرصفحه افزودن توابع هیدرات تعریف شده است، هدف پیوند است: افزودن توابع هیدرات. و موارد داخل پرانتز به‌عنوان پیوندهایی به یک نوع نمایش داده می‌شوند، plugin.HydrateFunc، و به یک ویژگی، plugin.Column.Hydrate. این شروع به نوشتن ویکی می کرد!

چیزی که هنوز نداشتیم، توانایی ایجاد صفحات ویکی جدید بود که در آن می‌توانیم مفاهیم سطح بالاتر را توضیح دهیم. نمای کلی مکانی برای انجام این کار بود، اما ما می‌خواستیم آن را برای روایت سفر نویسنده افزونه رزرو کنیم. کجا می توانیم مفهومی مانند جداول پویا را مورد بحث قرار دهیم، یک ویژگی پیشرفته که افزونه هایی مانند CSV را فعال می کند. هیچ طرح ثابتی ندارید و باید ستون‌ها را در جریان تعریف کنید؟

کای متوجه شد که نه تنها می‌توانیم بسته‌های فقط مستندات جدیدی برای چنین موضوعاتی ایجاد کنیم، بلکه می‌توانیم آنها را وارد کنیم تا نام آنها برای همان نوع پیوند کوتاهی که می‌توانیم با آن انجام دهیم در دسترس باشد، به عنوان مثال، [plugin HydrateFunc]. در سطح بالای doc.go او این کار را انجام داد:

package steampipe_plugin_sdk

import (
	"github.com/turbot/steampipe-plugin-sdk/v5/docs/dynamic_tables"
)

var forceImportDynamicPlugin dynamic_tables.ForceImport

و در /docs/dynamic_tables/doc.go این کار را انجام داد:

package dynamic_tables

type ForceImport string

حالا می‌توانیم یک جمله در نظری مانند این بنویسیم:

/*
Use [dynamic_tables] when you cannot know a table's schema in advance.
*/
package steampipe-plugin-sdk

و اصطلاح پرانتزی پیوندهای خودکار درست مانند هر نام دیگری در فضای نام کد.

اگر به نظر می‌رسد مشکلی بیش از ارزش آن است، می‌توانید ژیمناستیک وارداتی را نادیده بگیرید و فقط از یک پیوند خارجی استفاده کنید:

/*
Use [dynamic_tables] when you cannot know a table's schema in advance.


[dynamic_tables]: https://pkg.go.dev/github.com/turbot/steampipe-plugin-sdk/v5/docs/dynamic_tables
*/
package steampipe-plugin-sdk

در هر صورت، تجربه نویسنده اکنون کاملاً شبیه ویکی است. می‌توانید در صورت نیاز صفحات جدیدی ایجاد کنید، و آنها را در اسناد فرامتنی که در پایه کد قرار دارند، ببافید.

مسلماً استفاده از سیستم Go به روش‌هایی که در اینجا توضیح داده شد کمی دشوار بود. نحو نظر مانند Markdown است اما به طرز ناامیدکننده ای Markdown نیست. به بسیاری از قراردادهای قالب بندی ضمنی بستگی دارد. اگر این مسیر را طی کنید، به یک ابزار پیش نمایش محلی نیاز دارید، و خیلی واضح نیست که ابزاری که می خواهید godoc نیست، بلکه pkgsite است. اگر فرمان برو نصب کن golang.org/x/pkgsite/cmd/pkgsite@latest را کشف کرده بودیم از غم و اندوه زیادی نجات می یافتیم.

این برنامه نویسی با سواد چگونه است؟

اینطور نیست! کنوت در مقاله همنام خود نوشت:

برای پشتیبانی از این عمل، او سیستمی به نام web اختراع کرد که اجزای آن، tangle و weave، نویسنده برنامه را قادر می‌سازد تا آن را بگوید. داستان به زبانی که کد (در اصل، پاسکال) و مستندات (در اصل، TeX) را به روش روایی-اول ترکیب می کند. همانطور که مارک جیسون دومینوس در مقاله خود اشاره کرده است، روش‌های مدرن ما برای ترکیب کد و مستندات، و تولید اسناد از نظرات تعبیه‌شده، فقط به صورت سطحی شبیه تمرین کنوت است. litprog.html/” rel=”nofollow”>POD برنامه نویسی با سواد نیست (۲۰۰۰).

با این حال، اکنون که تمرین هکاتون ما به من چشیده است که کد به‌عنوان ویکی چه چیزی می‌تواند باشد، احساس می‌کنم گامی به سوی رویکرد داستان‌گویی که کنوت از آن حمایت می‌کند. به یاد بیاورید که او نام سیستم خود را web گذاشته بود، قبل از اینکه وب وجود داشته باشد که ما اکنون در آن ساکن هستیم. من نمی توانم ادعا کنم که ما اکنون برنامه نویسان باسوادی به معنای کنوتی هستیم، و همیشه به این فکر کرده ام که آیا فقط یک ذهن کنوتی می تواند آن دیدگاه اصلی را پیاده کند. اما این روش برای بهبود کیفیت روایت اسناد تولید شده به صورت خودکار به نظر گامی در جهت درست است.