به دنبال مستندات API یک کتابخانهء کوچک (AndroidAsync)

[Eshpilen]

من هرچی گشتم مستندات این رو پیدا نکردم: https://github.com/koush/AndroidAsync
انگار جدی جدی مستنداتی نداره!
فقط چندتا مثال محدود و کوچک داره.
بابا یه لیستی از کلاسها، متدها، یه توضیح مختصری راجع به هرکدام نداره یعنی؟
یعنی باید بشینیم خودمون تمام سورسش رو بخونیم سر دربیاریم؟!

[YN97]

چرا داره بین سورسش مشخصه دیگه کامنت هایی /** شروع میشن در مورد متد ها و فیلد ها توضیح میده. کافیه با javadoc مستنداتش رو بسازید.

[Eshpilen]

(17-09-1394، 06:57 ب.ظ)YN97 نوشته: چرا داره بین سورسش مشخصه دیگه کامنت هایی /** شروع میشن در مورد متد ها و فیلد ها توضیح میده. کافیه با javadoc مستنداتش رو بسازید.

من تاحالا با این چیزا کار نکردم.
میتونی کمکی راهنمایی چیزی بکنی منم همزمان میرم روی کارش ببینم کیه چیه چکار کنم

میگم خب خودشون این کار رو میکردن حالا ملت رو اینقدر سردرگم نمیکردن.
ضمنا فکر میکنم توضیحات توی کامنت به تنهایی یخورده کم باشه. هرچند از هیچی خیلی بهتره حداقل.

[YN97]

javadoc همراه jdk نصب میشه و از خط فرمان اجرا میشه. و help کاملی هم داره. کافیه سورس برنامه رو بهش بدین بعد مستندات رو به صورت html تولید میکنه.

[Eshpilen]

اوه همچین ساده هم نبودا!
ولی فکر کنم آخرش یافتم.
این فرمان زدم همش رو مستندسازی کرد:

javadoc.exe -d c:docs -sourcepath c:AndroidAsync-masterAndroidAsyncsrc -subpackages com

[ADMIN]

مشابه همین ابزار به اسم PHPDoc برای PHP هم وجود داره و قطعاً توی زبانهای دیگه هم مشابهش هست. اینجاست که کامنت نویسی استاندارد بدرد میخوره و اگه فرضاً خود فرد هم مستندات نساخت، از روی همون کامنتها میشه یه مستندات حداقلی تولید کرد و گراف ارتباط بین اشیاء رو هم ترسیم کرد.

[Eshpilen]

ولی مهندس یه چیزی که من شخصا یه زمانی تجربه کردم این بود که مثلا همون موقع که کدی مینوشتم، کلاسی درست میکردم، کامنت هم براش میذاشتم همونجا. چون بهرحال همون موقع آدم بهتر میدونه چی به چیه و راحتتر و سریعتر میتونه کامنت بذاره. ولی بعد دیدم کدها و ساختار برنامه در زمان توسعه زیاد تغییر میکنن، و من مجبورم دوباره و دوباره کامنت های اونا رو هم تغییر بدم و اصلاح و آپدیت کنم، و این کار مستعد خطا و فراموشی هم هست. پس به این نتیجه رسیدم که باید وقتی کدها به مراحل نهایی خودش رسید و دیگه تغییرات گسترده و اساسی درش احتمال کمی داشت، یعنی درواقع درست قبل از شروع مراحل انتشار، باید بیایم و کامنت گذاری کنیم. البته در این موقع شاید اون راحتی و سرعت دیگه نباشه و آدم ممکنه یکسری جزییات در کد تاحدی یادش رفته باشه، اما فکر میکنم در کل خیلی بهینه تر از کامنت گذاری درموقع کدنویسی هست که مدام مجبوری تغییرش بدی و خیلی وقتا کامنت های قبلی بطور کامل از بین میرن و بیهوده میشن.
نمیدونم شایدم این مسئله تاحدی بخاطر روش برنامه نویسی من بوده یا بخاطر اینکه هنوز تجربهء عملیاتی زیاد نداشتم در نتیجه میزان تغییرات گسترده در کدهام خیلی بیشتر از برنامه نویسان با تجربه تر بوده.
البته من فکر کنم یجا خونده بودم که بخاطر همین مسائل، مثلا اینکه براحتی پیش میاد که کامنت ها با آخرین نسخهء کدها هماهنگ نیستن و آپدیت نشدن (مثلا در اثر فراموش کردن)، بنابراین خیلی مهمه و یکی از روشها اینه که خود کد به اصطلاح self-document باشه، یعنی مثلا اسم متغییرها و کلاسها کاملا روشن و خوانا و به حد کافی توضیحی و پرمحتوی باشه که هرکس خوند بتونه حداکثر اطلاعات مفید رو ازشون بفهمه. حالا نه فقط نامگذاری identifier ها، بلکه کلا ساختار و الگوریتم کد طوری باشه که به ساده ترین و روشن ترین شکل ممکن باشه بالاترین خوانایی رو داشته باشه.


نظر شما در این مورد چیه؟

[ADMIN]

یه راه مناسب برای حل این مشکل اینه که توی پروژه یک نفر مخصوص تولید مستندات باشه. در پایان هر روز کاری بیاد کدها رو بررسی کنه و کامنتها رو بر اساس تغییراتی که توی اون روز اتفاق افتاده اصلاح کنه. فایلهای امروز رو با دیروز با کمک ابزارهای مقایسه خط به خط، مطابقت بده و تغییرات رو بفهمه (و اگه لازمه برای این کار، با برنامه نویسها در تماس باشه) و داکیومنت کار رو بروزرسانی کنه. توی پروژه های بزرگ از این روش استفاده میشه. درواقع یکنفر مسئول مستندات هست. برای مثال توی پروژه Yii2 هم به همین شکل کار شده و همونطور که میبینید، مستنداتش نسبت به نسخه 1.1 خیلی پیشرفت داشته.